TempMail API 文档

REST API v1 与 Webhooks

TempMailg 开发者 API 文档

使用此文档生成您的个人API密钥,连接专用用户API主机,读取邮箱消息,管理属于自己的邮箱,并将Temp Mail集成到您的应用程序或自动化中。

Bearer令牌认证 实时 Webhooks Gmail 与 Outlook 别名 JSON 响应
用户 API 基本 URL HTTPS
请求格式 只在Authorization Bearer头中使用您的API密钥,并保持端点URL清洁。

邮箱管理

获取允许的域名, 创建或切换邮箱, 选择允许的使用期限, 并删除拥有的地址。

GET https://v1.tempmailg.com/api/domains?type={type}
#

列出允许的域名

列出可用于创建临时电子邮件的可用域。按类型筛选,以仅查看您的订阅计划支持的免费、付费或自定义域。

参数 1
参数 位置 类型 状态 描述
type query string 可选
域层级过滤器。省略时在启用 premium-domain 访问时使用全部,否则使用免费。已识别的值: free, basic, pro, premium, custom, ultimate, all
默认: 账户依赖的
获取允许的域
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
这是否是自定义域名。
POST https://v1.tempmailg.com/api/emails
#

创建临时邮箱

创建一个拥有的临时邮箱。省略用户名和域名以进行随机生成,或提供允许的自定义用户名和允许的域名。provider 参数可以选择 Gmail 或 Outlook 别名生成。

参数 8
参数 位置 类型 状态 描述
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,而不是静默选择默认值。
创建邮箱
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 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。
POST https://v1.tempmailg.com/api/emails/{email}/{username}/{domain}
#

更新 / 切换邮箱

在验证当前邮箱所有权后,在新用户名和域名下创建或选择一个邮箱。此操作不会重命名旧邮箱或更改其现有的使用期限。当目标不同时时,旧邮箱会保留在历史记录中,并可能因活跃邮箱限制而被暂停。重新使用您自己的活跃目标会重新应用其请求的使用期限或计划默认值。

参数 9
参数 位置 类型 状态 描述
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>
使用属于自己的邮箱邮箱 {email}。 可选的请求体参数:lifetime(允许的取值:10m、1h、2h、1d、1w、1m、3m、6m、1y、unlimited)。 省略生命周期,或留空,以使用为您当前的月度/年度计划配置的默认电子邮件生命周期。发送诸如 1h 之类的允许的生命周期以覆盖该默认值。仅在将无限制设置为计划默认或明确请求且被允许时才使用无限制。 也接受正文参数 mailbox_lifetime 和 email_lifetime;按照以下顺序:lifetime、mailbox_lifetime、email_lifetime。无效或不允许的值将返回 HTTP 422,而不是静默选择默认值。
更新属于自己的邮箱
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 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。
DELETE https://v1.tempmailg.com/api/emails/{email}
#

删除邮箱

删除拥有的邮箱并调用其消息和文件清理。保留的邮箱记录可能在内部被软删除;该地址通过 API 将不再可用。

参数 3
参数 位置 类型 状态 描述
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 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
删除属于自己的邮箱
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 别名邮箱。

POST https://v1.tempmailg.com/api/gmail-alias/emails
#

创建 Gmail 别名

为已认证用户创建一个新的 Gmail 别名临时邮箱。

参数 8
参数 位置 类型 状态 描述
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 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
需要在您的订阅计划中启用 Gmail Alias API 权限,或通过 API Credit 套餐解锁。 可选参数: 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,而不是静默选择默认值。
创建 Gmail 别名邮箱
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 格式表示的绝对读取授权到期时间。安全性更改可能会提前撤销授权。
GET https://v1.tempmailg.com/api/outlook-alias/domains
#

Outlook 别名域

获取可用于邮箱生成的活跃 Outlook / Hotmail 别名域名。

需要在您的订阅计划中启用 Outlook 别名 API 权限,或通过 API 积分套餐解锁。 指示您的计划是否已解锁特定域名选择。
获取 Outlook 别名域
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。
POST https://v1.tempmailg.com/api/outlook-alias/emails
#

创建 Outlook 别名

为已认证用户创建一个新的 Outlook / Hotmail 别名临时邮箱。

参数 7
参数 位置 类型 状态 描述
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 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
需要在您的订阅计划中启用 Outlook 别名 API 权限,或通过 API 积分套餐解锁。 可选参数: 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,而不是静默选择默认值。
创建 Outlook 别名邮箱
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/文本消息,并流式传输附件。

GET https://v1.tempmailg.com/api/messages?email={email}
#

列出邮箱消息

检索可用的消息摘要和邮箱元数据。标准收件箱扫描返回最近的一批最多 25 条消息;这不是分页的完整历史端点。使用 GET /messages/{messageId} 获取完整正文和附件。

参数 2
参数 位置 类型 状态 描述
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>
电子邮件必须属于您的账户。标准和 Gmail 摘要包含 OTP 和 verification-link 字段;Outlook 还包括 from_name、snippet、received_at 和 has_attachments。提供商同步和缓存可能会导致新消息和计数延迟。
读取邮箱消息
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 摘要字段:是否存在附件元数据。下载可用性单独检查。
GET https://v1.tempmailg.com/api/messages/{messageId}
#

获取单条消息

通过其不透明的消息 ID 检索拥有的消息。返回正文格式和附件元数据。正文字段取决于消息格式;Outlook 添加了下面列出的特定提供商字段。

参数 2
参数 位置 类型 状态 描述
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>
读取一条消息
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 正文。
DELETE https://v1.tempmailg.com/api/messages/{messageId}
#

删除消息

删除一个属于自己的消息。

参数 3
参数 位置 类型 状态 描述
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 字符的密钥。使用相同的密钥重试相同的请求,以避免重复工作。
删除一条消息
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。
GET https://v1.tempmailg.com/api/messages/{messageId}/attachments/{filename}
#

下载附件

从属于自己的消息中下载附件。

参数 3
参数 位置 类型 状态 描述
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>
成功返回文件字节,而不是 JSON。文件过大返回 HTTP 403;缺失或不可用的本地文件返回 HTTP 404。将文件名进行 URL 编码作为单个路径段。仅有附件元数据并不保证可下载。
下载附件
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
下载行为 此端点直接返回请求的文件,而不是 JSON 正文。
响应字段
字段 类型 描述
Content-Disposition header
成功响应会下载请求的文件名。
body binary
成功时返回文件字节,而不是 JSON。错误返回 JSON,状态码为 non-2xx。

速率限制与配额

实时监控请求预算、速率限制和账户配额,而不消耗积分。

GET https://v1.tempmailg.com/api/rate-limit
#

速率限制与配额

检查您当前的速率限制和配额状态,而不会消耗任何 API 使用量。此端点免配额,不会扣除每月的 API 积分(滥用保护限制:每分钟 60 次请求)。

X-RateLimit-* 描述指示的请求配额;X-Quota-* 在可用时描述每月和已购买的容量。X-Mailbox-RateLimit-* 报告单独的邮箱创建/更新配额。仅针对邮箱的拒绝使用邮箱范围及其自己的重试窗口。分钟限制的拒绝可能省略配额信息。Retry-After 仅在计时重试时包含;禁用的访问可能需要更改账户。 在此成功的状态响应中,data.limit、data.remaining 和 data.reset 描述的是账户的分钟预算,而不是可支配的积分。data.quota 对象描述每月配额、积分余额和使用情况。现有的 data.monthly_limit、data.monthly_remaining 和 data.purchased_credits 字段仍是相应配额字段的别名。 成功的状态检查并不授权另一次 API 操作。操作仍然需要已启用的访问权限、可用配额以及通过所有适用限制的批准。配额快照并不保证已被进行中的请求预留的容量。
检查速率限制状态
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 字段的兼容别名;在计算余额时不要再次添加它。

邮箱 PIN 保护

输入 PIN 以继续。您的邮箱在本网站会话期间保持解锁。

您接受Cookies吗?

我们使用 cookies 来提升您的浏览体验。通过使用本网站,您同意我们的 cookie 政策。

更多