クイックセットアップチェックリスト
- ダッシュボードのAPI管理ページを開き、個人用APIキーを作成します。
- そこに表示される正確なユーザーAPIベースURLをコピーします。例: https://v1.tempmailg.com/api.
- すべてのリクエストをそのAPIホストに送信します Authorization: Bearer YOUR_USER_API_KEY および Accept: application/json.
- 同じダッシュボードページと、ユーザーAPIレスポンスで利用可能な場合はクオータヘッダーから、月間リクエストクォータを追跡します。成功した2xxリクエストのみがクオータにカウントされます。
認証フロー
- ダッシュボードのAPI Managementページから、個人のAPIキーを生成します。
- すべてのリクエストで、キーをBearerトークンとして送信します。
- API Managementページに表示される専用のユーザーAPIベースURLを使用します。
- 古いキーを無効にし、新しいキーをすぐに使用開始するために、いつでもキーを再生成します。
必須ヘッダー
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
レートリミット & クォータヘッダー
レートリミットヘッダーは示されたリクエスト予算を説明します。クォータ情報が利用可能な場合はクォータヘッダーが含まれます;分単位のリミット拒否は月間クォータ全体を計算しません。
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1729520000
X-Quota-Limit: 50000
X-Quota-Remaining: 48210
X-Quota-Used: 1790
X-Quota-Reset: 2026-11-01T00:00:00+00:00
X-RateLimit-Scope: account
Retry-After: 42 (when a timed retry is available)
X-RateLimit-Limit— プランで許可されている1分あたりの最大リクエスト数 (RPM)。X-RateLimit-Remaining— 現在の1分ウィンドウで残っているRPMリクエスト数。X-RateLimit-Reset— 現在の1分レートリミットウィンドウがリセットされるUnixタイムスタンプ。X-Quota-Limit— アカウントの月次および購入済みクレジット容量の合計。X-Quota-Remaining— 今月の残り利用可能な API リクエスト数。X-Quota-Used— 現在の請求期間中に使用された API リクエストの合計。X-Quota-Reset— 月間クォータがリセットされるISO-8601タイムスタンプ。X-RateLimit-Scope— ヘッダーで説明される予算: account, ip, status_endpoint, または mailbox。X-Mailbox-RateLimit-*— メールボックスの作成/更新予算を分離します。成功したメールボックスの応答は X-RateLimit-* のアカウント RPM を保持します; メールボックスのみの拒否はメールボックススコープと独自のリトライウィンドウを使用します。Retry-After— タイムリトライが適切になるまでの秒数です。無効化されたプランやクォータが枯渇している場合は、代わりにアカウント変更が必要になることがあるため、このヘッダーが常に存在するわけではありません。503 protection_unavailable— API保護ストレージまたは調整は一時的に利用できません。後でもう一度お試しください; これは支払い失敗やクレジットデビットではありません。
Mailbox Management
Fetch allowed domains, create, update lifetimes, switch, and delete temporary email addresses.
List Allowed Domains
List available domains for creating temporary emails. Filter by type to see only free, premium, or custom domains supported by your subscription plan.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
type
|
query | string | 任意 |
Domain tier filter. Allowed values: free, basic, pro, premium, custom, ultimate, all
デフォルト:
free
|
const response = await fetch('https://v1.tempmailg.com/api/domains?type=free', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/domains?type=free', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/domains?type=free');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/domains?type=free' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"requested_type": "free",
"plan": "pro",
"plan_name": "Pro Plan",
"allowed_types": [
"free",
"basic",
"pro",
"premium",
"custom",
"ultimate",
"all"
],
"domains": [
{
"domain": "example.com",
"type": "Free",
"custom": false
}
]
}
}
Create Temporary Mailbox
Create a new temporary email address. By default, a random email address is generated. You can customize the email username, domain, or domain type by providing the appropriate parameters in the JSON request body.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
username
|
body | string | 任意 |
Custom mailbox username prefix (subject to plan custom username permissions).
デフォルト:
Randomly generated
|
domain
|
body | string | 任意 |
One of the allowed domains returned by GET /domains.
デフォルト:
Default allowed domain
|
lifetime
|
body | string | 任意 |
Mailbox duration: 10m, 1h, 2h, 1d, 1w, 1m, or unlimited (also accepts mailbox_lifetime or email_lifetime).
デフォルト:
Plan default lifetime
|
provider
|
body | string | 任意 |
Mailbox provider: standard, gmail_alias, or outlook_alias.
デフォルト:
standard
|
username (custom username if allowed by plan), domain (allowed domain, e.g. example.com), lifetime (allowed values: 10m, 1h, 2h, 1d, 1w, 1m, unlimited), provider (standard, gmail_alias, outlook_alias). Omit lifetime, or leave it empty, to use the Default Email Lifetime configured for your current monthly/yearly plan. Send a permitted lifetime such as 1h to override that default. Unlimited is used only when configured as the plan default or explicitly requested and permitted. The body parameters mailbox_lifetime and email_lifetime are also accepted; the first non-empty value wins in this order: lifetime, mailbox_lifetime, email_lifetime. Invalid or disallowed values return HTTP 422 instead of silently selecting a default.const response = await fetch('https://v1.tempmailg.com/api/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"id": 2301,
"email": "customuser@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-10-30T06:08:15+00:00",
"expires_in_seconds": 86400,
"created_at": "2026-10-29T06:08:15+00:00",
"email_token": "encrypted-email-token"
}
}
Update / Switch Mailbox
Update or switch an existing owned mailbox to a new username and allowed domain. This operation applies only to mailboxes owned by the authenticated user.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
email
|
path | string | 必須 |
Current full email address of the owned mailbox to switch.
|
username
|
path | string | 必須 |
New desired username prefix.
|
domain
|
path | string | 必須 |
New allowed domain name.
|
lifetime
|
body | string | 任意 |
Optional new mailbox lifetime duration.
デフォルト:
Current remaining / plan default
|
lifetime (allowed values: 10m, 1h, 2h, 1d, 1w, 1m, unlimited). Omit lifetime, or leave it empty, to use the Default Email Lifetime configured for your current monthly/yearly plan. Send a permitted lifetime such as 1h to override that default. Unlimited is used only when configured as the plan default or explicitly requested and permitted. The body parameters mailbox_lifetime and email_lifetime are also accepted; the first non-empty value wins in this order: lifetime, mailbox_lifetime, email_lifetime. Invalid or disallowed values return HTTP 422 instead of silently selecting a default.const response = await fetch('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"id": 2302,
"email": "demo123@example.com",
"domain": "example.com",
"expire_at": "2026-10-29T06:18:15+00:00",
"expires_in_seconds": 600,
"created_at": "2026-10-29T06:08:15+00:00",
"email_token": "encrypted-email-token"
}
}
Delete Mailbox
Delete a temporary email address. The email address is immediately marked as expired and soft-deleted, along with all its associated messages.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
email
|
path | string | 必須 |
Full email address of the owned mailbox to delete.
|
const response = await fetch('https://v1.tempmailg.com/api/emails/demo123@example.com', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/emails/demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/emails/demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
Gmail と Outlook エイリアス
Generate high-reputation Gmail and Outlook/Hotmail alias mailboxes.
Create Gmail Alias
Create a new Gmail alias temporary mailbox owned by the authenticated user.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
mode
|
body | string | 任意 |
Generation mode: auto, dot, plus, or plus_word.
デフォルト:
auto
|
username
|
body | string | 任意 |
Custom alias username prefix.
デフォルト:
Auto-generated
|
domain
|
body | string | 任意 |
Allowed domain: gmail.com or googlemail.com.
デフォルト:
gmail.com
|
lifetime
|
body | string | 任意 |
Duration: 10m, 1h, 2h, 1d, 1w, 1m, or unlimited.
デフォルト:
Plan default lifetime
|
mode (auto, dot, plus, plus_word), username (custom alias username), domain (e.g. gmail.com, googlemail.com), lifetime (allowed values: 10m, 1h, 2h, 1d, 1w, 1m, unlimited). Omit lifetime, or leave it empty, to use the Default Email Lifetime configured for your current monthly/yearly plan. Send a permitted lifetime such as 1h to override that default. Unlimited is used only when configured as the plan default or explicitly requested and permitted. The body parameters mailbox_lifetime and email_lifetime are also accepted; the first non-empty value wins in this order: lifetime, mailbox_lifetime, email_lifetime. Invalid or disallowed values return HTTP 422 instead of silently selecting a default.const response = await fetch('https://v1.tempmailg.com/api/gmail-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/gmail-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/gmail-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/gmail-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"id": 2305,
"email": "myname.alias123@gmail.com",
"domain": "gmail.com",
"provider": "gmail_alias",
"expire_at": "2026-10-29T07:08:16+00:00",
"expires_in_seconds": 3600,
"created_at": "2026-10-29T06:08:16+00:00",
"email_token": "encrypted-email-token"
}
}
Outlook Alias Domains
Fetch active Outlook / Hotmail alias domains available for mailbox generation.
const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/domains', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/outlook-alias/domains', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/domains');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/outlook-alias/domains' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"domains": [
{
"domain": "outlook.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
},
{
"domain": "hotmail.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
}
]
}
}
Create Outlook Alias
Create a new Outlook / Hotmail alias temporary mailbox owned by the authenticated user.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
domain
|
body | string | 任意 |
Target Outlook domain, e.g. outlook.com or hotmail.com.
デフォルト:
First available
|
username
|
body | string | 任意 |
Custom alias prefix if allowed by subscription.
デフォルト:
Auto-generated
|
lifetime
|
body | string | 任意 |
Duration: 10m, 1h, 2h, 1d, 1w, 1m, or unlimited.
デフォルト:
Plan default lifetime
|
domain (e.g. outlook.com, hotmail.com), username (custom alias username), lifetime (allowed values: 10m, 1h, 2h, 1d, 1w, 1m, unlimited). Omit lifetime, or leave it empty, to use the Default Email Lifetime configured for your current monthly/yearly plan. Send a permitted lifetime such as 1h to override that default. Unlimited is used only when configured as the plan default or explicitly requested and permitted. The body parameters mailbox_lifetime and email_lifetime are also accepted; the first non-empty value wins in this order: lifetime, mailbox_lifetime, email_lifetime. Invalid or disallowed values return HTTP 422 instead of silently selecting a default.const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/outlook-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/outlook-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"id": 2306,
"email": "fastuser_alias45@outlook.com",
"domain": "outlook.com",
"provider": "outlook_alias",
"expire_at": "2026-10-29T07:08:17+00:00",
"expires_in_seconds": 3600,
"created_at": "2026-10-29T06:08:17+00:00",
"email_token": "encrypted-email-token"
}
}
Messages & Attachments
Fetch incoming inboxes, read full HTML/text messages, and stream attachments.
List Mailbox Messages
Retrieve all messages from a temporary email inbox. Returns message details, including message ID, sender, subject, received date, read status, and email preview.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
email
|
query | string | 必須 |
Full email address of the owned mailbox to read messages from.
|
const response = await fetch('https://v1.tempmailg.com/api/messages?email=demo123@example.com', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages?email=demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages?email=demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages?email=demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"mailbox": "randombox@example.com",
"messages": [
{
"is_seen": false,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "randombox@example.com",
"receivedAt": "2026-10-29 06:08:17",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"content": "<p>Hello from the inbox.</p>",
"attachments": [
{
"name": "file.txt",
"extension": "txt",
"size": 91,
"url": "https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt"
}
]
}
]
}
Get Single Message
Retrieve a specific email message by its ID (`hash_id`). Returns the full message content, including the HTML body and attachments.
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
messageId
|
path | string | 必須 |
Unique message ID returned in the message list.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"data": {
"is_seen": true,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "randombox@example.com",
"receivedAt": "2026-10-29 06:08:17",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"content": "<p>Hello from the inbox.</p>",
"attachments": [
{
"name": "file.txt",
"extension": "txt",
"size": 91,
"url": "https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt"
}
]
}
}
メッセージを削除
所有メッセージを1件削除します。
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
messageId
|
path | string | 必須 |
Unique message ID string to permanently delete.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
Download Attachment
所有メッセージから添付ファイルをダウンロードします。
| パラメータ | 場所 | 種類 | ステータス | 説明 |
|---|---|---|---|---|
messageId
|
path | string | 必須 |
ID of the message containing the file.
|
filename
|
path | string | 必須 |
Filename and extension of the attachment to download.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const blob = await response.blob();
const downloadUrl = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = downloadUrl;
link.download = 'file.txt';
document.body.appendChild(link);
link.click();
link.remove();
window.URL.revokeObjectURL(downloadUrl);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', headers=headers, stream=True, timeout=30)
response.raise_for_status()
with open('file.txt', 'wb') as handle:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
handle.write(chunk)
<?php
$fileHandle = fopen('file.txt', 'w');
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_FILE => $fileHandle,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
if (curl_exec($ch) === false) {
fclose($fileHandle);
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
fclose($fileHandle);
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY' \
--output file.txt
Rate Limits & Quotas
Monitor real-time request budgets, rate limits, and account quotas without consuming credits.
Rate Limit & Quota
Check your current rate limit and quota status without consuming any API usage. This endpoint is quota-free and does not deduct monthly API credits (abuse protection limit: 60 requests/min).
const response = await fetch('https://v1.tempmailg.com/api/rate-limit', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/rate-limit', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/rate-limit');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/rate-limit' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
例レスポンス
200 OK • JSON{
"status": "success",
"data": {
"limit": 60,
"remaining": 45,
"reset": 32,
"plan": "premium",
"monthly_limit": 50000,
"monthly_remaining": 48210,
"purchased_credits": 5000,
"quota": {
"enabled": true,
"user_api_status": true,
"plan_name": "Premium Plan",
"period": "2026-10",
"base_limit": 50000,
"extra_requests": 0,
"monthly_limit": 50000,
"monthly_remaining": 48210,
"used": 1790,
"purchased_credits": 5000,
"bonus_credits": 1000,
"direct_purchased_credits": 4000,
"remaining": 53210,
"unlimited": false,
"usage_percent": 3,
"reset_at": "2026-11-01T00:00:00+00:00"
}
}
}
| フィールド | 種類 | 説明 |
|---|---|---|
data.limit |
integer|string | Account requests-per-minute limit. The string unlimited denotes an unlimited minute budget; this is independent of monthly quota. |
data.remaining |
integer|string | Remaining account minute-budget slots, or the string unlimited. A positive value does not mean that API credits remain. |
data.reset |
integer | Seconds for the account minute window, not the monthly quota reset. Disabled or unlimited minute budgets can retain a nominal 60-second value; this does not promise access after waiting. |
data.plan |
string | Current plan tag. The readable plan name is provided separately in data.quota.plan_name. |
data.quota.enabled |
boolean | Whether global and plan/credit API access is enabled. This does not indicate remaining capacity or replace the user API switch. |
data.quota.user_api_status |
boolean | Whether the user has enabled their User API switch. Operations require this switch as well as enabled access and available capacity. |
data.quota.plan_name |
string | Readable name of the current plan. |
data.quota.period |
string | Calendar-month usage period in YYYY-MM format, using the application timezone; not necessarily the subscription billing period. |
data.quota.base_limit |
integer | Base monthly plan allowance. A value of -1 means unlimited. |
data.quota.extra_requests |
integer | Additional monthly allowance granted for the current usage period; separate from purchased credits. |
data.quota.monthly_limit |
integer | Base allowance plus current-period extra requests. A value of -1 means unlimited. Purchased credits are not included. |
data.quota.monthly_remaining |
integer|null | Remaining finite monthly allowance, or null when monthly quota is unlimited. Null must not be interpreted as zero. |
data.quota.used |
integer | Successful, counted API operations in the current usage period, including operations using credits. Status checks do not increase this value. |
data.quota.purchased_credits |
integer | Current credit balance, including active plan bonus credits. Bonus credits must not be added to this balance a second time. |
data.quota.bonus_credits |
integer | Active plan-bonus portion of the credit balance; a breakdown of purchased_credits, not additional capacity. |
data.quota.direct_purchased_credits |
integer | Credit balance excluding the active plan-bonus portion. This value plus bonus_credits equals purchased_credits. |
data.quota.remaining |
integer|null | Monthly remaining allowance plus the current credit balance, without double-counting bonuses. Null means unlimited monthly quota. Individual feature permissions and other request limits still apply. |
data.quota.unlimited |
boolean | Whether monthly quota is unlimited. This does not make the account minute budget or other feature limits unlimited. |
data.quota.usage_percent |
integer | Dashboard-compatible rounded percentage from 0 to 100: used divided by used plus remaining, multiplied by 100. It includes available credit capacity, so recharging can lower the percentage. It is 0 for unlimited quota or a zero-sized pool; it is not the minute rate-limit percentage or an access decision. |
data.quota.reset_at |
string | ISO-8601 timestamp with timezone offset for the next calendar-month quota reset. This is not the subscription expiry date, and the monthly reset does not refill purchased credits. |
メールボックス Webhook(リアルタイムプッシュ)
REST API(GET /messages)を繰り返しポーリングして受信メールを確認する代わりに、Webhook を設定して新しいメールをリアルタイムであなたのサーバーまたは自動化ワークフローにプッシュできます。
サポートされているWebhookイベント
各Webhookは1つ以上のイベントタイプに登録できます。これらのトリガーのいずれかが発火すると、エンドポイントにイベント通知が送信されます。
Dispatched in real time whenever a new message reaches the selected mailbox.
Dispatched when the temporary mailbox expires and webhook processing is paused.
Dispatched when an expired mailbox becomes active again under plan rules.
Dispatched right before the webhook and its mailbox are deleted.
リクエストヘッダーとHMAC署名検証
すべてのウェブフック配信には特殊なセキュリティヘッダーが含まれています。X-TempMailg-Signatureヘッダーを使用して、TempMailgから本物のリクエストが送信されたことを確認し、改ざんされていないことを検証してください。
| ヘッダー名 | 例の値 | 説明 |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Standard identifier for the webhook delivery worker. |
X-TempMailg-Event |
email.received | The type of event that triggered this delivery. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | Unique UUID assigned to this delivery attempt. |
X-TempMailg-Timestamp |
1725192000 | Unix epoch timestamp indicating when the request was initiated. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | HMAC-SHA256 signature calculated from {timestamp}.{raw_body} using your secret. |
X-TempMailg-Test |
false | True when dispatched by the "Send Test Ping" feature in your dashboard. |
署名は、次の文字列に対してHMACでSHA256を使用して計算されます:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
サンプルイベントペイロード(email.received)
HTTP POST リクエストボディ内で application/json として送信されます。
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-10-29T06:08:20+00:00",
"test": false,
"mailbox": {
"id": 1024,
"email": "developer@v1.tempmailg.com"
},
"data": {
"message_id": "7a8b9c0d1e2f",
"subject": "Your Verification Code: 948201",
"from": "auth@service.com",
"to": "developer@v1.tempmailg.com",
"date": "2026-10-29T06:08:20+00:00",
"attachments_count": 0,
"text_preview": "Hello, your one-time verification code is 948201. It will expire in 10 minutes.",
"email_url": "https://tempmailg.com/mailbox/1024?message=7a8b9c0d1e2f",
"inbox_url": "https://tempmailg.com/mailbox/1024"
}
}
受信側実装例
言語を選択して、Webhook の受信方法と HMAC 署名を安全に検証する方法を確認してください。
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = 'your_webhook_signing_secret';
// Capture raw body buffer for HMAC-SHA256 signature verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString('utf8');
}
}));
app.post('/webhook', (req, res) => {
const timestamp = req.headers['x-tempmailg-timestamp'];
const signatureHeader = req.headers['x-tempmailg-signature'] || '';
// Calculate HMAC-SHA256 signature
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${timestamp}.${req.rawBody}`)
.digest('hex');
// Verify signature
if (signatureHeader !== expectedSignature) {
return res.status(401).json({ error: 'Invalid webhook signature' });
}
const { event, mailbox, data } = req.body;
console.log(`[Event: ${event}] Mailbox: ${mailbox.email}`);
if (event === 'email.received') {
console.log(`From: ${data.from}`);
console.log(`Subject: ${data.subject}`);
console.log(`Preview: ${data.text_preview}`);
}
// Acknowledge receipt with HTTP 200
res.status(200).json({ received: true });
});
app.listen(3000, () => console.log('Webhook receiver running on port 3000'));
from flask import Flask, request, jsonify
import hmac
import hashlib
app = Flask(__name__)
WEBHOOK_SECRET = b"your_webhook_signing_secret"
@app.route("/webhook", methods=["POST"])
def handle_webhook():
timestamp = request.headers.get("X-TempMailg-Timestamp", "")
signature_header = request.headers.get("X-TempMailg-Signature", "")
# Calculate expected HMAC-SHA256 signature
raw_body = request.get_data()
signed_payload = f"{timestamp}.".encode("utf-8") + raw_body
expected_signature = "sha256=" + hmac.new(
WEBHOOK_SECRET, signed_payload, hashlib.sha256
).hexdigest()
# Verify signature securely
if not hmac.compare_digest(signature_header, expected_signature):
return jsonify({"error": "Invalid signature"}), 401
payload = request.get_json()
event = payload.get("event")
mailbox = payload.get("mailbox", {}).get("email")
data = payload.get("data", {})
print(f"[{event}] Mailbox: {mailbox}")
if event == "email.received":
print(f"From: {data.get('from')}")
print(f"Subject: {data.get('subject')}")
print(f"Preview: {data.get('text_preview')}")
# Return 200 OK to acknowledge receipt
return jsonify({"received": True}), 200
if __name__ == "__main__":
app.run(port=5000)
<?php
$secret = 'your_webhook_signing_secret';
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TEMPMAILG_TIMESTAMP'] ?? '';
$receivedSignature = $_SERVER['HTTP_X_TEMPMAILG_SIGNATURE'] ?? '';
// Calculate HMAC-SHA256 signature
$expectedSignature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
// Verify signature
if (!hash_equals($expectedSignature, $receivedSignature)) {
http_response_code(401);
echo json_encode(['error' => 'Invalid signature']);
exit;
}
$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? '';
$mailbox = $payload['mailbox']['email'] ?? '';
$data = $payload['data'] ?? [];
if ($event === 'email.received') {
$sender = $data['from'] ?? '';
$subject = $data['subject'] ?? '';
$preview = $data['text_preview'] ?? '';
// Process new incoming email...
}
// Acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);
対応プラットフォームと自動化統合
TempMailg の Webhook は、標準的な HTTPS エンドポイントと主要なノーコード/自動化プラットフォームで、すぐに使用できます:
共通のエラーとトラブルシューティング
これらは、ユーザーAPIを統合する際に表示される可能性のある最も一般的なレスポンスコードです。
無効または欠落しているBearerトークン。
現在のユーザープランでは、ユーザーAPIアクセスが無効になっています。
リソースは許可されたホストで見つからなかった、またはユーザーに属しません。
メールボックスが期限切れまたは非アクティブです。
検証に失敗した、または要求されたメールボックス/ドメインが許可されていません。
A request limit, disabled plan, exhausted quota, or cooldown prevented the operation. Check the reason and available budget headers. Retry-After is optional.
Protection storage or coordination could not be verified. Retry after the indicated delay. This response is not a failed payment.
クイックチェックリスト
- 401 Unauthorized - Bearerトークンが欠けている、間違っている、取り消された、またはコピーが間違っている。
- 403 Forbidden - 現在のプランには、ユーザーAPIへのアクセス権がありません。
- 404 Not Found - リソースが見つからないか、無効なパラメータです。
- 410 Gone / Expired - メールボックスの有効期限が切れた、またはアクティブではありません。
- 429 Rate Limited - 月間クレジット限度額に達しました — クレジットを購入するかリセットを待つ
推奨される次のステップ
サインインしている場合は、API Management を開いて、デバッグを開始する前に、キー、クォータ、プランのアクセス状態、および正確なユーザー API ベース URL を確認してください。