快速设置清单
- 打开您的仪表板API管理页面并创建您的个人API密钥。
- 复制显示的确切用户API基URL,例如 https://v1.tempmailg.com/api.
- 将每个请求发送到该API主机,使用 Authorization: Bearer YOUR_USER_API_KEY 和 Accept: application/json.
- 在同一仪表板页面以及在用户 API 响应中可用的配额标头中跟踪您的每月请求配额。只有成功的 2xx 请求计入配额。
身份验证流程
- 从仪表板 API 管理页面生成您的个人 API 密钥。
- 在每个请求中将密钥作为 Bearer 令牌发送。
- 使用在 API 管理页面中显示的专用用户 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— 每分钟允许的最大请求数 (RPM)(适用于您的计划)。X-RateLimit-Remaining— 当前分钟窗口中剩余的 RPM 请求。X-RateLimit-Reset— 当前分钟速率限制窗口重置时的 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 保护存储或协调暂时不可用。请稍后重试;这不是支付失败或信用扣款。
邮箱管理
获取允许的域名, 创建或切换邮箱, 选择允许的使用期限, 并删除拥有的地址。
列出允许的域名
列出可用于创建临时电子邮件的可用域。按类型筛选,以仅查看您的订阅计划支持的免费、付费或自定义域。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
type
|
query | string | 可选 |
域层级过滤器。省略时在启用 premium-domain 访问时使用全部,否则使用免费。已识别的值: free, basic, pro, premium, custom, ultimate, all
默认:
账户依赖的
|
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
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
}
]
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.requested_type |
string | 已应用域过滤器。 |
data.plan |
string | 当前计划标签。 |
data.plan_name |
string | 当前计划的可读名称。 |
data.allowed_types |
array<string> | 此账户可用的域过滤器。已识别的过滤器仍可能因您的计划而被禁止。 |
data.domains |
array | 过滤后可选择的域;空数组是有效的。 |
data.domains[].domain |
string | 可选择的域名。 |
data.domains[].type |
string | 可读域层级标签。 |
data.domains[].custom |
boolean | 这是否是自定义域名。 |
创建临时邮箱
创建一个拥有的临时邮箱。省略用户名和域名以进行随机生成,或提供允许的自定义用户名和允许的域名。provider 参数可以选择 Gmail 或 Outlook 别名生成。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
username
|
body | string | 可选 |
可选的自定义用户名:2 到 64 个 ASCII 字母、数字、点、下划线或连字符。需要计划权限;也接受 custom_username。
默认:
随机生成
|
domain
|
body | string | 可选 |
GET /domains 返回的允许域名之一。省略时会随机选择一个允许的域名。
默认:
随机允许的域
|
lifetime
|
body | string | 可选 |
允许的值:
10m — 10 分钟
1h — 1 小时
2h — 2 小时
1d — 1 天
1w — 1 周
1m — 30 天
3m — 90 天
6m — 180 天
1y — 365 天
unlimited — 无限
默认:
计划默认寿命
|
provider
|
body | string | 可选 |
邮箱提供商:standard,gmail_alias,或 outlook_alias。
默认:
standard
|
pin_enabled
|
body | boolean | 可选 |
在计划允许的情况下,可为新邮箱提供可选的 PIN 保护。这不会更改现有邮箱的 PIN。
默认:
false
|
pin
|
body | string | 可选 |
当 pin_enabled 为 true 时必需:一个 6 到 8 位的 PIN,作为字符串发送以保留前导零。
|
pin_confirmation
|
body | string | 可选 |
当 pin_enabled 为 true 时必填。必须与 pin 完全匹配。
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
username (如果计划允许,则自定义用户名), domain (允许的域,例如 example.com), lifetime (允许的值: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). 省略生命周期,或留空,以使用为您当前的月度/年度计划配置的默认电子邮件生命周期。发送诸如 1h 之类的允许的生命周期以覆盖该默认值。仅在将无限制设置为计划默认或明确请求且被允许时才使用无限制。 也接受正文参数 mailbox_lifetime 和 email_lifetime;按照以下顺序:lifetime、mailbox_lifetime、email_lifetime。无效或不允许的值将返回 HTTP 422,而不是静默选择默认值。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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"data": {
"id": 2301,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-20T02:18:18+00:00",
"expires_in_seconds": 86399.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:18+00:00",
"email_token": "encrypted-email-token"
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.id |
integer | 邮箱 ID。为每个邮箱生成的 ID、地址和令牌各不相同。 |
data.pin_protected |
boolean | 此邮箱是否启用 PIN 保护。不返回 PIN 或 PIN 哈希。 |
data.email |
string | 已生成完整的邮箱地址。 |
data.domain |
string | 生成的邮箱的域名。 |
data.provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
data.expire_at |
string|null | 有效期为 ISO-8601 时间戳,或为 null 表示无限邮箱。 |
data.expires_in_seconds |
number|null | 计算时剩余的秒数为非负数;可以是小数秒。Null 表示无限,而不是零。 |
data.mailbox_state |
string | 当前邮箱状态: 活跃, 已暂停, 已过期, 或 未激活。 |
data.receiving_enabled |
boolean | 此邮箱当前是否接受传入消息。 |
data.message_count |
integer | 已知的总消息计数;它可以反映最近一次邮箱同步。 |
data.unread_message_count |
integer | 已知未读消息计数;它可以反映上一次邮箱同步。 |
data.last_message_received_at |
string|null | 最后已知的接收消息时间(ISO-8601 格式),如果不可用则为 null。 |
data.message_count_synced_at |
string|null | 上一次消息计数同步时间(ISO-8601 格式),同步前为 null。 |
data.created_at |
string|null | 邮箱创建时间(ISO-8601 格式)。 |
data.email_token |
string | 不透明的加密邮箱引用。它不能替代 Bearer 身份验证、所有权检查或 PIN 授权。 |
data.pin_grant |
object | 条件:激活的 PIN 受保护邮箱创建会返回此读取授权;普通未受保护的创建则省略它。 |
data.pin_grant.mailbox_id |
integer | 条件读取授权绑定的邮箱 ID。 |
data.pin_grant.unlock_token |
string | 用于 X-Mailbox-Unlock 的不透明读取令牌,使用相同的所有者凭证。请保持私密并存于内存中;读取授权不允许删除。 |
data.pin_grant.scope |
string | 条件创建授权的范围读取. |
data.pin_grant.idle_timeout_seconds |
integer | 读取授权允许的空闲时间,通常为 3600 秒。 |
data.pin_grant.absolute_timeout_seconds |
integer | 读取授权的最大生命周期,通常为86400秒。 |
data.pin_grant.expires_at |
string | 当前读取授权的到期时间,采用 ISO-8601 格式。 |
data.pin_grant.absolute_expires_at |
string | 以 ISO-8601 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。 |
更新 / 切换邮箱
在验证当前邮箱所有权后,在新用户名和域名下创建或选择一个邮箱。此操作不会重命名旧邮箱或更改其现有的使用期限。当目标不同时时,旧邮箱会保留在历史记录中,并可能因活跃邮箱限制而被暂停。重新使用您自己的活跃目标会重新应用其请求的使用期限或计划默认值。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
email
|
path | string | 必需 |
要切换的已拥有邮箱的当前完整电子邮件地址。对每个路径段进行 URL 编码;将加号编码为 %2B。
|
username
|
path | string | 必需 |
新期望的用户名:2 到 64 个字母数字字符;受自定义用户名权限限制。
|
domain
|
path | string | 必需 |
新的允许域名。
|
lifetime
|
body | string | 可选 |
允许的值:
10m — 10 分钟
1h — 1 小时
2h — 2 小时
1d — 1 天
1w — 1 周
1m — 30 天
3m — 90 天
6m — 180 天
1y — 365 天
unlimited — 无限
默认:
计划默认寿命
|
pin_enabled
|
body | boolean | 可选 |
在计划允许的情况下,可为新邮箱提供可选的 PIN 保护。这不会更改现有邮箱的 PIN。
默认:
false
|
pin
|
body | string | 可选 |
当 pin_enabled 为 true 时必需:一个 6 到 8 位的 PIN,作为字符串发送以保留前导零。
|
pin_confirmation
|
body | string | 可选 |
当 pin_enabled 为 true 时必填。必须与 pin 完全匹配。
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用读取 unlock_token。首先向 PIN 解锁 URL POST pin 和 scope=read。保持正常的 Bearer 身份验证。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime(允许的取值:10m、1h、2h、1d、1w、1m、3m、6m、1y、unlimited)。 省略生命周期,或留空,以使用为您当前的月度/年度计划配置的默认电子邮件生命周期。发送诸如 1h 之类的允许的生命周期以覆盖该默认值。仅在将无限制设置为计划默认或明确请求且被允许时才使用无限制。 也接受正文参数 mailbox_lifetime 和 email_lifetime;按照以下顺序:lifetime、mailbox_lifetime、email_lifetime。无效或不允许的值将返回 HTTP 422,而不是静默选择默认值。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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"data": {
"id": 2302,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-19T02:28:18+00:00",
"expires_in_seconds": 599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:18+00:00",
"email_token": "encrypted-email-token"
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.id |
integer | 邮箱 ID。为每个邮箱生成的 ID、地址和令牌各不相同。 |
data.pin_protected |
boolean | 此邮箱是否启用 PIN 保护。不返回 PIN 或 PIN 哈希。 |
data.email |
string | 已生成完整的邮箱地址。 |
data.domain |
string | 生成的邮箱的域名。 |
data.provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
data.expire_at |
string|null | 有效期为 ISO-8601 时间戳,或为 null 表示无限邮箱。 |
data.expires_in_seconds |
number|null | 计算时剩余的秒数为非负数;可以是小数秒。Null 表示无限,而不是零。 |
data.mailbox_state |
string | 当前邮箱状态: 活跃, 已暂停, 已过期, 或 未激活。 |
data.receiving_enabled |
boolean | 此邮箱当前是否接受传入消息。 |
data.message_count |
integer | 已知的总消息计数;它可以反映最近一次邮箱同步。 |
data.unread_message_count |
integer | 已知未读消息计数;它可以反映上一次邮箱同步。 |
data.last_message_received_at |
string|null | 最后已知的接收消息时间(ISO-8601 格式),如果不可用则为 null。 |
data.message_count_synced_at |
string|null | 上一次消息计数同步时间(ISO-8601 格式),同步前为 null。 |
data.created_at |
string|null | 邮箱创建时间(ISO-8601 格式)。 |
data.email_token |
string | 不透明的加密邮箱引用。它不能替代 Bearer 身份验证、所有权检查或 PIN 授权。 |
data.pin_grant |
object | 条件:激活的 PIN 受保护邮箱创建会返回此读取授权;普通未受保护的创建则省略它。 |
data.pin_grant.mailbox_id |
integer | 条件读取授权绑定的邮箱 ID。 |
data.pin_grant.unlock_token |
string | 用于 X-Mailbox-Unlock 的不透明读取令牌,使用相同的所有者凭证。请保持私密并存于内存中;读取授权不允许删除。 |
data.pin_grant.scope |
string | 条件创建授权的范围读取. |
data.pin_grant.idle_timeout_seconds |
integer | 读取授权允许的空闲时间,通常为 3600 秒。 |
data.pin_grant.absolute_timeout_seconds |
integer | 读取授权的最大生命周期,通常为86400秒。 |
data.pin_grant.expires_at |
string | 当前读取授权的到期时间,采用 ISO-8601 格式。 |
data.pin_grant.absolute_expires_at |
string | 以 ISO-8601 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。 |
删除邮箱
删除拥有的邮箱并调用其消息和文件清理。保留的邮箱记录可能在内部被软删除;该地址通过 API 将不再可用。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
email
|
path | string | 必需 |
要删除的拥有的邮箱的完整电子邮件地址。对地址进行 URL 编码;将加号编码为 %2B。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用一次性删除 unlock_token。首先 POST pin,scope=delete,并使用 423 响应返回的 action/target_id 到 PIN 解锁 URL。读取令牌无法删除。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
message |
string | 删除的结果。缺少的资源返回 HTTP 404。 |
Gmail 与 Outlook 别名
生成高信誉的 Gmail 和 Outlook/Hotmail 别名邮箱。
创建 Gmail 别名
为已认证用户创建一个新的 Gmail 别名临时邮箱。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
mode
|
body | string | 可选 |
生成模式:auto、dot、plus 或 plus_dot。也接受 gmail_alias_mode。如果不允许选择样式,则使用 auto。
默认:
auto
|
username
|
body | string | 可选 |
可选的自定义别名后缀:2 到 32 个 ASCII 字母或数字,规范为小写;受功能权限限制。也接受 custom_username 或 alias_username。
默认:
自动生成的
|
domain
|
body | string | 可选 |
使用随机、gmail.com 或 googlemail.com;alias_domain 也被接受。省略或不可用的域选择权限将使用随机。
默认:
random
|
lifetime
|
body | string | 可选 |
允许的值:
10m — 10 分钟
1h — 1 小时
2h — 2 小时
1d — 1 天
1w — 1 周
1m — 30 天
3m — 90 天
6m — 180 天
1y — 365 天
unlimited — 无限
默认:
计划默认寿命
|
pin_enabled
|
body | boolean | 可选 |
在计划允许的情况下,可为新邮箱提供可选的 PIN 保护。这不会更改现有邮箱的 PIN。
默认:
false
|
pin
|
body | string | 可选 |
当 pin_enabled 为 true 时必需:一个 6 到 8 位的 PIN,作为字符串发送以保留前导零。
|
pin_confirmation
|
body | string | 可选 |
当 pin_enabled 为 true 时必填。必须与 pin 完全匹配。
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
mode (auto, dot, plus, plus_dot), username (自定义别名用户名), domain (例如:gmail.com, googlemail.com), lifetime (允许的值: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). 省略生命周期,或留空,以使用为您当前的月度/年度计划配置的默认电子邮件生命周期。发送诸如 1h 之类的允许的生命周期以覆盖该默认值。仅在将无限制设置为计划默认或明确请求且被允许时才使用无限制。 也接受正文参数 mailbox_lifetime 和 email_lifetime;按照以下顺序:lifetime、mailbox_lifetime、email_lifetime。无效或不允许的值将返回 HTTP 422,而不是静默选择默认值。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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"data": {
"id": 2305,
"pin_protected": false,
"email": "example+alias123@gmail.com",
"domain": "gmail.com",
"provider": "gmail_alias",
"expire_at": "2026-11-19T03:18:18+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:18+00:00",
"email_token": "encrypted-email-token"
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.id |
integer | 邮箱 ID。为每个邮箱生成的 ID、地址和令牌各不相同。 |
data.pin_protected |
boolean | 此邮箱是否启用 PIN 保护。不返回 PIN 或 PIN 哈希。 |
data.email |
string | 已生成完整的邮箱地址。 |
data.domain |
string | 生成的邮箱的域名。 |
data.provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
data.expire_at |
string|null | 有效期为 ISO-8601 时间戳,或为 null 表示无限邮箱。 |
data.expires_in_seconds |
number|null | 计算时剩余的秒数为非负数;可以是小数秒。Null 表示无限,而不是零。 |
data.mailbox_state |
string | 当前邮箱状态: 活跃, 已暂停, 已过期, 或 未激活。 |
data.receiving_enabled |
boolean | 此邮箱当前是否接受传入消息。 |
data.message_count |
integer | 已知的总消息计数;它可以反映最近一次邮箱同步。 |
data.unread_message_count |
integer | 已知未读消息计数;它可以反映上一次邮箱同步。 |
data.last_message_received_at |
string|null | 最后已知的接收消息时间(ISO-8601 格式),如果不可用则为 null。 |
data.message_count_synced_at |
string|null | 上一次消息计数同步时间(ISO-8601 格式),同步前为 null。 |
data.created_at |
string|null | 邮箱创建时间(ISO-8601 格式)。 |
data.email_token |
string | 不透明的加密邮箱引用。它不能替代 Bearer 身份验证、所有权检查或 PIN 授权。 |
data.pin_grant |
object | 条件:激活的 PIN 受保护邮箱创建会返回此读取授权;普通未受保护的创建则省略它。 |
data.pin_grant.mailbox_id |
integer | 条件读取授权绑定的邮箱 ID。 |
data.pin_grant.unlock_token |
string | 用于 X-Mailbox-Unlock 的不透明读取令牌,使用相同的所有者凭证。请保持私密并存于内存中;读取授权不允许删除。 |
data.pin_grant.scope |
string | 条件创建授权的范围读取. |
data.pin_grant.idle_timeout_seconds |
integer | 读取授权允许的空闲时间,通常为 3600 秒。 |
data.pin_grant.absolute_timeout_seconds |
integer | 读取授权的最大生命周期,通常为86400秒。 |
data.pin_grant.expires_at |
string | 当前读取授权的到期时间,采用 ISO-8601 格式。 |
data.pin_grant.absolute_expires_at |
string | 以 ISO-8601 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。 |
Outlook 别名域
获取可用于邮箱生成的活跃 Outlook / Hotmail 别名域名。
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
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
}
]
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.domains |
array | 活跃的 Outlook/Hotmail 域;空数组也是有效的。 |
data.domains[].domain |
string | 可用的域名。 |
data.domains[].type |
string | 可读的提供者标签。 |
data.domains[].selectable |
boolean | 您的账户是否可以明确选择此域名。 |
data.domains[].locked |
boolean | 是否已锁定您账户的显式域选择。 |
data.domains[].disabled_reason |
string|null | 域名选择被锁定的原因,或在可选择时为 null。 |
创建 Outlook 别名
为已认证用户创建一个新的 Outlook / Hotmail 别名临时邮箱。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
domain
|
body | string | 可选 |
使用随机或从 GET /outlook-alias/domains 获取的域名;也接受 outlook_alias_domain。如果没有选择权限,则使用随机。
默认:
随机可用域
|
username
|
body | string | 可选 |
可选的自定义别名后缀:2 到 32 个 ASCII 字母或数字,规范为小写;受功能权限限制。也接受 custom_username 或 alias_username。
默认:
自动生成的
|
lifetime
|
body | string | 可选 |
允许的值:
10m — 10 分钟
1h — 1 小时
2h — 2 小时
1d — 1 天
1w — 1 周
1m — 30 天
3m — 90 天
6m — 180 天
1y — 365 天
unlimited — 无限
默认:
计划默认寿命
|
pin_enabled
|
body | boolean | 可选 |
在计划允许的情况下,可为新邮箱提供可选的 PIN 保护。这不会更改现有邮箱的 PIN。
默认:
false
|
pin
|
body | string | 可选 |
当 pin_enabled 为 true 时必需:一个 6 到 8 位的 PIN,作为字符串发送以保留前导零。
|
pin_confirmation
|
body | string | 可选 |
当 pin_enabled 为 true 时必填。必须与 pin 完全匹配。
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
domain (例如 outlook.com, hotmail.com), username (自定义别名用户名), lifetime (允许的值: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). 省略生命周期,或留空,以使用为您当前的月度/年度计划配置的默认电子邮件生命周期。发送诸如 1h 之类的允许的生命周期以覆盖该默认值。仅在将无限制设置为计划默认或明确请求且被允许时才使用无限制。 也接受正文参数 mailbox_lifetime 和 email_lifetime;按照以下顺序:lifetime、mailbox_lifetime、email_lifetime。无效或不允许的值将返回 HTTP 422,而不是静默选择默认值。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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"data": {
"id": 2306,
"pin_protected": false,
"email": "example+alias45@outlook.com",
"domain": "outlook.com",
"provider": "outlook_alias",
"expire_at": "2026-11-19T03:18:18+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:18+00:00",
"email_token": "encrypted-email-token"
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.id |
integer | 邮箱 ID。为每个邮箱生成的 ID、地址和令牌各不相同。 |
data.pin_protected |
boolean | 此邮箱是否启用 PIN 保护。不返回 PIN 或 PIN 哈希。 |
data.email |
string | 已生成完整的邮箱地址。 |
data.domain |
string | 生成的邮箱的域名。 |
data.provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
data.expire_at |
string|null | 有效期为 ISO-8601 时间戳,或为 null 表示无限邮箱。 |
data.expires_in_seconds |
number|null | 计算时剩余的秒数为非负数;可以是小数秒。Null 表示无限,而不是零。 |
data.mailbox_state |
string | 当前邮箱状态: 活跃, 已暂停, 已过期, 或 未激活。 |
data.receiving_enabled |
boolean | 此邮箱当前是否接受传入消息。 |
data.message_count |
integer | 已知的总消息计数;它可以反映最近一次邮箱同步。 |
data.unread_message_count |
integer | 已知未读消息计数;它可以反映上一次邮箱同步。 |
data.last_message_received_at |
string|null | 最后已知的接收消息时间(ISO-8601 格式),如果不可用则为 null。 |
data.message_count_synced_at |
string|null | 上一次消息计数同步时间(ISO-8601 格式),同步前为 null。 |
data.created_at |
string|null | 邮箱创建时间(ISO-8601 格式)。 |
data.email_token |
string | 不透明的加密邮箱引用。它不能替代 Bearer 身份验证、所有权检查或 PIN 授权。 |
data.pin_grant |
object | 条件:激活的 PIN 受保护邮箱创建会返回此读取授权;普通未受保护的创建则省略它。 |
data.pin_grant.mailbox_id |
integer | 条件读取授权绑定的邮箱 ID。 |
data.pin_grant.unlock_token |
string | 用于 X-Mailbox-Unlock 的不透明读取令牌,使用相同的所有者凭证。请保持私密并存于内存中;读取授权不允许删除。 |
data.pin_grant.scope |
string | 条件创建授权的范围读取. |
data.pin_grant.idle_timeout_seconds |
integer | 读取授权允许的空闲时间,通常为 3600 秒。 |
data.pin_grant.absolute_timeout_seconds |
integer | 读取授权的最大生命周期,通常为86400秒。 |
data.pin_grant.expires_at |
string | 当前读取授权的到期时间,采用 ISO-8601 格式。 |
data.pin_grant.absolute_expires_at |
string | 以 ISO-8601 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。 |
消息与附件
获取收件箱中的邮件,读取完整的 HTML/文本消息,并流式传输附件。
列出邮箱消息
检索可用的消息摘要和邮箱元数据。标准收件箱扫描返回最近的一批最多 25 条消息;这不是分页的完整历史端点。使用 GET /messages/{messageId} 获取完整正文和附件。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
email
|
query | string | 必需 |
完整的拥有邮箱地址,用于读取邮件。对查询值进行 URL 编码;将加号编码为 %2B。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用读取 unlock_token。首先向 PIN 解锁 URL POST pin 和 scope=read。保持正常的 Bearer 身份验证。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"mailbox": "demo123@example.com",
"email_token": "encrypted-email-token",
"messages": [
{
"is_seen": false,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"receivedAt": "2026-11-19 02:18:18",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"otp": null,
"otp_locked": false,
"verification_link": null,
"verification_link_locked": false
}
],
"mailbox_provider": "standard",
"mailbox_state": "active",
"expire_at": "2026-11-20T02:18:18+00:00",
"expires_in_seconds": 86399.75,
"receiving_enabled": true,
"mailbox_limit": {
"limit": 50,
"limit_label": "50",
"active_count": 1,
"paused_count": 0,
"paused_mailboxes": [],
"remaining": 49,
"remaining_label": "49",
"reached": false,
"blocked": false,
"provider": "standard"
},
"message_count": 1,
"unread_message_count": 1,
"last_message_received_at": "2026-11-19T02:18:18+00:00",
"message_count_synced_at": "2026-11-19T02:18:18+00:00"
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
mailbox |
string | 请求的邮件的邮箱地址。 |
email_token |
string | 不透明的加密邮箱引用;仍需正常身份验证。 |
mailbox_provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
messages |
array | 消息摘要。空收件箱返回空数组;检索单条消息以获取其正文和附件。 |
expire_at |
string|null | 有效期为 ISO-8601 时间戳,或为 null 表示无限邮箱。 |
expires_in_seconds |
number|null | 计算时剩余的秒数为非负数;可以是小数秒。Null 表示无限,而不是零。 |
mailbox_state |
string | 当前邮箱状态: 活跃, 已暂停, 已过期, 或 未激活。 |
receiving_enabled |
boolean | 此邮箱当前是否接受传入消息。 |
message_count |
integer | 已知的总消息计数;它可以反映最近一次邮箱同步。 |
unread_message_count |
integer | 已知未读消息计数;它可以反映上一次邮箱同步。 |
last_message_received_at |
string|null | 最后已知的接收消息时间(ISO-8601 格式),如果不可用则为 null。 |
message_count_synced_at |
string|null | 上一次消息计数同步时间(ISO-8601 格式),同步前为 null。 |
mailbox_limit.limit |
integer | 此提供商的活动邮箱限制;-1 表示无限。 |
mailbox_limit.limit_label |
string | 邮箱限制的显示标签。 |
mailbox_limit.active_count |
integer | 此提供商的活跃邮箱数量。 |
mailbox_limit.paused_count |
integer | 此提供商的已暂停邮箱数量。 |
mailbox_limit.paused_mailboxes |
array<string> | 由于邮箱限制,地址已暂停。 |
mailbox_limit.remaining |
integer | 剩余活动邮箱槽位;-1 表示无限。这不是 API 请求配额。 |
mailbox_limit.remaining_label |
string | 显示剩余邮箱槽位的标签。 |
mailbox_limit.reached |
boolean | 是否已达到活动邮箱限制。 |
mailbox_limit.blocked |
boolean | 活动邮箱限制是否为零。 |
mailbox_limit.provider |
string|null | 适用于邮箱限制的提供商。 |
messages[].id |
string | 在单条消息、删除和附件端点使用的不透明消息 ID。 |
messages[].is_seen |
boolean | 消息是否已标记为已读。 |
messages[].subject |
string | 邮件主题。 |
messages[].from |
string | 发件人显示名称或地址。 |
messages[].from_email |
string | 发件人电子邮件地址。 |
messages[].receivedAt |
string | 接收时间(使用应用时区),格式为 YYYY-MM-DD HH:mm:ss。 |
messages[].otp |
string|null | 在可用且允许时检测一次性代码;否则为 null。 |
messages[].otp_locked |
boolean | 检测到的一次性代码是否因功能权限而被隐藏。 |
messages[].verification_link |
string|null | 在可用且允许的情况下检测到验证 URL;否则为 null。 |
messages[].verification_link_locked |
boolean | 检测到的验证链接是否因功能权限而被隐藏。 |
messages[].from_name |
string|null | Outlook 摘要字段:原始发件人姓名。标准和 Gmail 摘要中不存在。 |
messages[].snippet |
string|null | Outlook 摘要字段:短消息预览。 |
messages[].received_at |
string|null | Outlook 摘要字段:ISO-8601 接收时间,已知时。 |
messages[].has_attachments |
boolean | Outlook 摘要字段:是否存在附件元数据。下载可用性单独检查。 |
获取单条消息
通过其不透明的消息 ID 检索拥有的消息。返回正文格式和附件元数据。正文字段取决于消息格式;Outlook 添加了下面列出的特定提供商字段。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
messageId
|
path | string | 必需 |
在消息列表中返回的唯一消息 ID。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用读取 unlock_token。首先向 PIN 解锁 URL POST pin 和 scope=read。保持正常的 Bearer 身份验证。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"data": {
"is_seen": true,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "demo123@example.com",
"mailbox_provider": "standard",
"receivedAt": "2026-11-19 02:18:18",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"html_content": "<p>Hello from the inbox.</p>",
"text_content": "<pre>Hello from the inbox.</pre>",
"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"
}
]
}
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
data.id |
string | 不透明的消息 ID。 |
data.is_seen |
boolean | 消息读取状态。读取可以将其标记为已查看;缓存数据可以反映早期状态。 |
data.subject |
string | 邮件主题。 |
data.from |
string | 发件人显示名称或地址。 |
data.from_email |
string | 发件人电子邮件地址。 |
data.to |
string | 收件人邮箱地址。 |
data.mailbox_provider |
string | 邮箱提供商:standard,gmail_alias,或 outlook_alias。 |
data.receivedAt |
string | 接收时间(使用应用时区),格式为 YYYY-MM-DD HH:mm:ss。 |
data.html |
boolean | 消息是否包含 HTML 正文。 |
data.html_content |
string | 当存在时为 HTML 正文。没有 HTML 的标准消息可以省略此字段。请将消息内容视为不可信。 |
data.text_content |
string | 文本主体(如果存在);标准消息可能在 pre 元素中包含转义文本,或省略此字段。 |
data.content |
string | 首选显示正文,若可用通常为 HTML。 |
data.attachments |
array | 附件元数据,或空数组。下载需要正常身份验证和相应的 PIN 授权。 |
data.attachments[].name |
string | 下载时将文件名进行 URL 编码,作为单个路径段。 |
data.attachments[].size |
integer | 附件大小(字节)。 |
data.attachments[].url |
string | 已将经过身份验证的用户 API 下载 URL 添加到带有文件名的附件。URL 并不保证本地文件可用。 |
data.attachments[].extension |
string | 标准/Gmail 元数据字段:提供时的文件扩展名。 |
data.attachments[].id |
string | Outlook 元数据字段:提供程序附件 ID。 |
data.attachments[].content_type |
string | Outlook 元数据字段:MIME 内容类型。 |
data.from_name |
string|null | Outlook 详细字段:原始发件人姓名。 |
data.to_email |
string|null | Outlook 详细字段:原始收件人地址。 |
data.received_at |
string|null | Outlook 详细字段:ISO-8601 接收时间。 |
data.has_html |
boolean | Outlook 详细字段:是否存在 HTML 正文。 |
删除消息
删除一个属于自己的消息。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
messageId
|
path | string | 必需 |
唯一的消息 ID 字符串,用于永久删除。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用一次性删除 unlock_token。首先 POST pin,scope=delete,并使用 423 响应返回的 action/target_id 到 PIN 解锁 URL。读取令牌无法删除。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | 可选 |
PIN-protected 创建或删除需要:一个稳定的 16 到 128 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
|
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
boolean | 操作是否成功。 |
message |
string | 删除的结果。缺少的资源返回 HTTP 404。 |
下载附件
从属于自己的消息中下载附件。
| 参数 | 位置 | 类型 | 状态 | 描述 |
|---|---|---|---|---|
messageId
|
path | string | 必需 |
包含文件的消息 ID。
|
filename
|
path | string | 必需 |
要下载的附件的文件名和扩展名。
|
X-Mailbox-Unlock
|
header | string | 可选 |
标题,仅限受保护的邮箱:使用读取 unlock_token。首先向 PIN 解锁 URL POST pin 和 scope=read。保持正常的 Bearer 身份验证。 <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
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
| 字段 | 类型 | 描述 |
|---|---|---|
Content-Disposition |
header | 成功响应会下载请求的文件名。 |
body |
binary | 成功时返回文件字节,而不是 JSON。错误返回 JSON,状态码为 non-2xx。 |
速率限制与配额
实时监控请求预算、速率限制和账户配额,而不消耗积分。
速率限制与配额
检查您当前的速率限制和配额状态,而不会消耗任何 API 使用量。此端点免配额,不会扣除每月的 API 积分(滥用保护限制:每分钟 60 次请求)。
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'
使用合成数据的示例响应。ID、地址、令牌、时间戳、计划限制和计数会有所不同。示例生命周期不会覆盖您的计划默认值。响应字段描述标识可为空的字段和提供商特定的字段。
示例响应
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 | 账户每分钟请求限制。字符串 unlimited 表示无限的分钟预算;这与每月配额无关。 |
data.remaining |
integer|string | 剩余账户分钟预算槽位,或字符串 unlimited。正值并不意味着 API 积分仍然可用。 |
data.reset |
integer | 账户分钟窗口的秒数,而不是每月配额重置。禁用或无限的分钟预算可以保留名义上的 60 秒值;这并不保证等待后即可访问。 |
data.plan |
string | 当前计划标签。可读的计划名称在 data.quota.plan_name 中单独提供。 |
data.quota.enabled |
boolean | 是否启用了全局和计划/信用 API 访问。这并不表示剩余容量,也不取代用户 API 开关。 |
data.quota.user_api_status |
boolean | 用户是否已启用其用户 API 开关。操作需要此开关以及已启用的访问权限和可用容量。 |
data.quota.plan_name |
string | 当前计划的可读名称。 |
data.quota.period |
string | 日历月份使用期间,采用 YYYY-MM 格式,使用应用时区;不一定是订阅计费期间。 |
data.quota.base_limit |
integer | 基础月度计划配额。值为 -1 表示无限。 |
data.quota.extra_requests |
integer | 在当前使用期间授予额外的月度配额;与已购买的积分分开。 |
data.quota.monthly_limit |
integer | 基础配额加上当前周期的额外请求。-1 表示无限。不包括已购买的积分。 |
data.quota.monthly_remaining |
integer|null | 剩余的有限月度配额,若月配额无限则为 null。null 不应被解释为零。 |
data.quota.used |
integer | 成功的、计入当前使用周期的 API 操作次数,包括使用积分的操作。状态检查不计入此值。 |
data.quota.purchased_credits |
integer | 当前信用余额,包括活跃计划的奖励积分。奖励积分不得再次计入此余额。 |
data.quota.bonus_credits |
integer | 信用余额中活跃计划奖励部分;已购买的 purchased_credits 细分,而非额外容量。 |
data.quota.direct_purchased_credits |
integer | 信用余额(不包括当前计划的奖励部分)。此数值加上 bonus_credits 等于 purchased_credits。 |
data.quota.remaining |
integer|null | 每月剩余配额加上当前信用余额,且不重复计算奖励。Null 表示无限的月配额。仍然适用各项功能权限和其他请求限制。 |
data.quota.unlimited |
boolean | 每月配额是否无限。这并不意味着账户的分钟预算或其他功能限制也无限。 |
data.quota.usage_percent |
integer | 仪表板兼容的 0 到 100 的四舍五入百分比:已使用量除以已使用量加剩余量,再乘以 100。它包括可用信用容量,因此充值可以降低该百分比。对于无限配额或零大小的池,该值为 0;它不是每分钟速率限制的百分比,也不是访问决策。 |
data.quota.reset_at |
string | 下一个日历月配额重置的 ISO-8601 时间戳(含时区偏移)。这不是订阅到期日期,且每月重置不会补充已购买的积分。 |
status |
string | 此状态端点的字面成功。其他成功的邮箱端点使用布尔值 true。 |
data.monthly_limit |
integer | 对应 data.quota 字段的兼容别名;在计算余额时不要再次添加它。 |
data.monthly_remaining |
integer|null | 对应 data.quota 字段的兼容别名;在计算余额时不要再次添加它。 |
data.purchased_credits |
integer | 对应 data.quota 字段的兼容别名;在计算余额时不要再次添加它。 |
邮箱网钩(实时推送)
不必反复轮询 REST API(GET /messages)来检查收到的邮件,而是可以配置 Webhook 将新邮件实时推送到您的服务器或自动化工作流程。
支持的 Webhook 事件
每个 webhook 可以订阅一个或多个事件类型。当其中任意触发器触发时,您的端点会收到事件通知。
每当新消息到达所选邮箱时,实时派发。
当临时邮箱过期且 webhook 处理被暂停时发送。
当已过期的邮箱在计划规则下重新激活时发送。
在 webhook 及其邮箱被删除之前立即发送。
请求头部与 HMAC 签名验证
每个网钩(webhook)传递都包含特殊的安全头部。使用 **X-TempMailg-Signature** 头部验证,以确保收到的请求确实由 TempMailg 合法发送,且未被篡改。
| 标题名称 | 示例值 | 描述 |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Webhook 交付工作者的标准标识符。 |
X-TempMailg-Event |
email.received | 触发此交付的事件类型。 |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | 分配给此投递尝试的唯一 UUID。 |
X-TempMailg-Timestamp |
1725192000 | Unix epoch 时间戳,指示请求发起的时间。 |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | 使用您的密钥对 {timestamp}.{raw_body} 计算的 HMAC-SHA256 签名。 |
X-TempMailg-Test |
false | 当通过仪表板中的 \"Send Test Ping\" 功能派发时为真。 |
签名是通过 HMAC 使用 SHA256 对字符串计算得到的:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
示例事件有效载荷(email.received)
以 application/json 格式在 HTTP POST 请求体中发送
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:18:18+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-11-19T02:18:18+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 Webhooks 开箱即用,支持标准 HTTPS 端点和领先的无代码/自动化平台:
常见错误和故障排除
这些是您在集成用户 API 时可能看到的最常见的响应代码。
无效、缺失或已撤销的 Bearer 令牌。
所有权、功能权限、域访问或附件大小阻止了此操作。请检查响应代码和消息。
资源未在允许的主机上找到,或不属于用户。
操作密钥已在不同细节下重复使用,另有操作正在进行,或邮箱安全已更改。重试前请检查代码。
邮箱已过期或不活动。
无效的参数、不允许的生命周期、别名容量不足、无效的 PIN 设置或缺失/无效的 Idempotency-Key 阻止了操作。
受保护的邮箱需要有效的范围化 X-Mailbox-Unlock 令牌。使用响应中的 action 和 target_id 进行删除。在重试之前,必须解决锁定或恢复要求。
请求限制、计划已禁用、配额耗尽或冷却时间阻止了操作。检查原因和可用预算头。Retry-After 为可选项。
服务器无法完成此操作。对于受保护的创建或删除,请在重试时保留相同的请求和 Idempotency-Key。
保护存储或协调无法验证。请在指示的延迟后重试。此响应不是支付失败。
快速清单
- 401 Unauthorized - Bearer 令牌缺失、错误、吊销或复制错误。
- 403 Forbidden - 当前计划不具备用户 API 访问权限。
- 404 Not Found - 资源未找到或参数无效
- 410 Gone / Expired - 邮箱已过期或不再活跃。
- 429 Rate Limited - 检查响应原因和预算标头。Retry-After 仅适用于时间限制;信用耗尽或访问被禁用可能需要更改账户。