入门
欢迎使用 TempMail 开发者 API。我们有一些很棒的功能,例如...
- 免费层级无需 API 密钥注册
- Plus 和 Ultra 用户的自定义域
- 还有更多!查看我们的 价格页面 了解更多信息。
如果不使用库,所有的POST请求必须将Content-Type头设置为application/json!
选择您的库

Python
NodeJS

Java
HTTP
$ pip3 install tempmail-lolAPI 类型
邮件
一个邮件对象,当您检查您的收件箱时返回。
| 名称 | 类型 | 描述 |
|---|---|---|
| from | string | 邮件发送者 |
| to | string | 接收者(您的临时邮箱) |
| subject | string | 邮件主题 |
| body | string | 纯文本正文,可能为空 |
| html | ?string | 邮件 HTML(可能为空) |
| date | number | 接收邮件时的 Unix 时间戳 |
收件箱
一个收件箱对象,包含邮箱地址和访问令牌。
| 名称 | 类型 | 描述 |
|---|---|---|
| address | string | 创建的邮箱地址 |
| token | string | 查看收件箱的访问令牌 |
收件箱生命周期
收件箱的生命周期取决于您的订阅层级。
| 订阅层级 | 生命周期 |
|---|---|
| 免费(无订阅) | 一小时 |
| TempMail Plus | 十小时 |
| TempMail Ultra | 三十小时 |
收件箱生命周期可以通过重新请求创建收件箱方法延长(仅适用于自定义域)。
创建收件箱
创建收件箱方法可以使用 GET 或 POST。POST 方法允许您自定义选项,例如收件箱的前缀和域。
GET 方法目前仅存在于遗留原因。
from TempMail import TempMail
tmp = TempMail("optional-api-key")
inb = tmp.createInbox()
# Or... use a prefix
inb = tmp.createInbox(prefix = "joe")
# You can use a setup custom domain here
inb = tmp.createInbox(domain = "mycustomdomain.com", prefix = "optional")
正文
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| domain | ?string | 收件箱的域,或随机。可以是自定义域。 | null |
| prefix | ?string | 收件箱的前缀,或随机。 | null |
响应 (201)
| 名称 | 类型 | 描述 |
|---|---|---|
| address | string | 收件箱的邮箱地址。 |
| token | string | 收件箱的令牌。 |
获取邮件
使用创建邮箱时收到的令牌获取邮件。如果您丢失了令牌,您将无法再访问邮件,除非是自定义域(请不要为此联系支持,我们无法出于法律原因给您邮箱地址)。
from TempMail import TempMail
tmp = TempMail("optional-api-key")
inb = tmp.createInbox()
emails = tmp.getEmails(inb.token)
print("Emails:")
for email in emails:
print("\tSender: " + email.sender)
print("\tRecipient: " + email.recipient)
print("\tSubject: " + email.subject)
print("\tBody: " + email.body)
print("\tHTML: " + str(email.html)) # may be None
print("\tDate: " + str(email.date)) # Unix timestamp in milliseconds
查询
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| token | string | 访问收件箱的令牌 | null |
响应 (200)
| 名称 | 类型 | 描述 |
|---|---|---|
| emails | Email[] | 从服务器接收到的邮件数组 |
| expired | boolean | 如果收件箱过期为真(见收件箱生命周期) |
正文
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| domain | string | 在 TempMail 上注册的域 | null |
Response (200)
| 名称 | 类型 | 描述 |
|---|---|---|
| uuid | string | 为您的域记录设置的 UUID(见下文) |
在您的域下添加此记录为[uuid].yourdomain.com,并将值设置为tm-custom-domain-verification。
如果您使用子域,请设置为[uuid].subdomain.yourdomain.com。
响应 (4xx)
| 名称 | 类型 | 描述 |
|---|---|---|
| error | string | 解释为何无法设置域的错误。 |
创建自定义域地址
与创建普通收件箱的方式相同,使用您的域创建自定义域收件箱!
注意事项:
- 必须使用创建域的UUID时使用的相同账户
prefix参数将设置为无前导数字的普通前缀
from TempMail import TempMail
tmp = TempMail("API Key required for custom domains")
inb = tmp.createInbox()
inb = tmp.createInbox(domain = "mycustomdomain.com", prefix = "optional")
正文
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| domain | string | 您的自定义域。 | null |
| prefix | ?string | 收件箱的邮箱地址(@之前的部分),或随机。 | null |
响应 (201)
| 名称 | 类型 | 描述 |
|---|---|---|
| address | string | 收件箱的邮箱地址。 |
| token | string | 收件箱的令牌。 |
如果您丢失了收件箱的令牌,请使用相同的前缀再次调用该方法。收件箱的生命周期将根据您的订阅延长。您可以无限次延长。
使用获取邮件的方法检查收件箱。
私有 Webhooks
设置私有 webhooks,以便您域的所有邮件直接发送到您的 webhook。
需要有效的 TempMail Ultra 订阅。
您必须已经为自定义域设置好域([uuid].domain.com)。
Body
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| domain | string | 设置 webhook 的域 | null |
| url | string | 邮件将转发到的 webhook URL | null |
响应 (200)
| 名称 | 类型 | 描述 |
|---|---|---|
| success | true | 总是为真 |
| message | string | 成功信息消息 |
响应 (4xx)
| 名称 | 类型 | 描述 |
|---|---|---|
| error | string | 包含错误详细信息的消息 |
您还可以使用域作为查询参数 DELETE /private_webhook 来删除它。
标准 Webhooks
在您创建的每个标准邮箱上设置标准 webhooks。邮件将转发到您的 webhook。
需要有效的 TempMail Ultra 订阅。
这不会追溯应用于现有邮件。
正文
| 参数 | 类型 | 描述 | 默认 |
|---|---|---|---|
| url | string | 邮件将转发到的 webhook URL | null |
响应 (200)
| 名称 | 类型 | 描述 |
|---|---|---|
| success | true | 总是为真 |
响应 (4xx)
| 名称 | 类型 | 描述 |
|---|---|---|
| error | string | 包含错误详细信息的消息 |
您还可以使用 DELETE /webhook 从您的账户中删除它。
API v3 Overview NEW
API v3 is the new, consistent TempMail API. It adds account-level inbox management, a wait-for-email long poll, raw .eml downloads, per-inbox webhooks with automatic retries and delivery logs, custom domain management, a list of TempMail's own domains, scoped API keys, and a usage endpoint.
What changed from v2:
- Fetches consume exactly what they return. Emails you receive in a response are deleted; emails excluded by your filters (
since,from,limit) stay in the inbox. v2 wipes the whole inbox on every read. - Errors are consistent. Every error is
{ "error": { "code", "message" } }with a matching HTTP status-never a 200. - Rate limits are visible. Responses carry
x-ratelimit-limit,x-ratelimit-remainingandx-ratelimit-resetheaders (reset is a unix timestamp in seconds). 429 responses includeretry-after. - v2 stays supported. Inboxes are shared between versions; v3 has its own create and fetch endpoints, but tokens work on both.
Base URL: https://api.tempmail.lol/v3
# account endpoints accept either key type:
Authorization: Bearer tempmail.20260101.abcdef... # primary key
Authorization: Bearer tempmail.sk.abcdef... # scoped key
# error envelope (here: HTTP 403)
{
"error": {
"code": "insufficient_scope",
"message": "This API key does not have the required scope: domains:read",
"required_scope": "domains:read"
}
}Scoped API Keys
Create additional API keys that can only do specific things, so your CI pipeline or a third-party integration never holds your full account credential. The key secret is returned once on creation and only a hash is stored.
Keys are managed with your primary API key (or the website), a scoped key can never manage keys.
Scopes
| Scope | Grants |
|---|---|
| inboxes:create | Create inboxes (works on v1/v2 create endpoints too) |
| inboxes:read | List your inboxes |
| webhooks:read | Read webhook config and delivery logs |
| webhooks:write | Set/remove per-inbox webhooks |
| domains:read | List/inspect custom domains |
| domains:write | Register/verify/remove custom domains |
| usage:read | Read usage & quota |
/v3/keyslist keys/v3/keyscreate a key/v3/keys/:idrename / re-scope / revoke/v3/keys/:iddelete a keycurl -X POST https://api.tempmail.lol/v3/keys \
-H "Authorization: Bearer $PRIMARY_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "ci key", "scopes": ["inboxes:create", "inboxes:read"]}'
# 201 -> { "key": "tempmail.sk....", "id": "...", "scopes": [...], ... }
# the "key" field is shown ONCE. store it nowCreate & Manage Inboxes
Create inboxes anonymously (free tier, per-IP limits) or with an API key (per-account limits, longer lifespans, account ownership). Inboxes created with a key belong to your account and can be listed with the inboxes:read scope; per-inbox endpoints are authorized by the inbox token itself.
POST /v3/inboxes - body (all optional)
| Parameter | Type | Description | Default |
|---|---|---|---|
| prefix | ?string | Local part prefix (a-z, 0-9, _, -) | random |
| domain | ?string | A TempMail domain (see TempMail Domains), or a custom domain verified to your account. Plus/Ultra accounts draw random domains from their own premium pool. | random |
| community | ?boolean | Prefer a community domain | false |
GET /v3/inboxes - query
| Parameter | Type | Description | Default |
|---|---|---|---|
| limit | ?number | Page size (max 200) | 50 |
| cursor | ?string | next_cursor from the previous page | null |
| include_expired | ?boolean | Also return expired inboxes | false |
/v3/inboxescreate an inbox/v3/inboxeslist your inboxes/v3/inboxes/:tokenmetadata + email count/v3/inboxes/:tokendelete inbox + its emailscurl -X POST https://api.tempmail.lol/v3/inboxes \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"prefix": "ci-run-42"}'
# 201
{
"address": "[email protected]",
"token": "...",
"created_at": "2026-07-16T00:22:22.000Z",
"expires_at": 1784269342568,
"expired": false,
"webhook_configured": false
}Fetch Emails & Raw .eml
Fetching emails consumes what it returns: emails in the response are deleted, while emails excluded by since or limit stay in the inbox (v2 deletes everything on read).
Raw RFC822 source is a TempMail Ultra feature. For Ultra-owned inboxes each fetched email includes a raw field with the exact MIME source received over SMTP (null if it was not captured). The standalone /raw endpoint downloads a .eml for an email that has NOT been consumed yet - useful with the email_id from webhook delivery logs. If the verbatim source is unavailable, a reconstructed .eml is served (marked with x-tempmail-reconstructed: true).
GET /v3/inboxes/:token/emails - query
| Parameter | Type | Description | Default |
|---|---|---|---|
| since | ?number | Only emails with date >= this unix ms timestamp | 0 |
| limit | ?number | Max emails returned (max 200) | 100 |
/v3/inboxes/:token/emailsfetch + consume/v3/inboxes/:token/emails/:iddelete without reading/v3/inboxes/:token/emails/:id/rawdownload .eml (Ultra)curl -OJ https://api.tempmail.lol/v3/inboxes/$TOKEN/emails/$ID/raw
# -> Content-Type: message/rfc822
# Content-Disposition: attachment; filename="<id>.eml"
# x-tempmail-reconstructed: false
# without Ultra -> 403
# { "error": { "code": "tier_required", "required_tier": "ultra", ... } }Wait for Email (long poll)
Blocks until an email matching your filters arrives, or the timeout passes - one request instead of a polling loop. Perfect for signup flows and CI: request the OTP, then wait for it.
Matched emails are returned and consumed; emails that do not match the from/since filters stay in the inbox untouched.
Query
| Parameter | Type | Description | Default |
|---|---|---|---|
| timeout | ?number | Seconds to wait (max 60) | 30 |
| from | ?string | Sender filter, wildcards allowed (*@example.com) | null |
| since | ?number | Ignore emails older than this unix ms timestamp | 0 |
At most 2 concurrent /wait requests per inbox. A timeout is still HTTP 200, with "timed_out": true and an empty emails array.
curl "https://api.tempmail.lol/v3/inboxes/$TOKEN/wait?\
from=*@example.com&timeout=30"
# matched emails are consumed on return
{
"emails": [{
"id": "6a58244f...",
"from": "[email protected]",
"subject": "Your verification code is 482913",
"body": "Code: 482913",
"raw": "From: [email protected]\r\n...", // Ultra only
...
}],
"timed_out": false,
"waited_ms": 2311
}Per-Inbox Webhooks & Delivery Logs
Attach a webhook to a single inbox (TempMail Ultra): new mail to that inbox is POSTed to your URL. Failed deliveries are retried automatically with backoff - 30s, 5m, 30m, 2h after the initial attempt (5 attempts total).
Every delivery and each attempt (status code, error, duration) is logged for 7 days and queryable - this covers account-wide (v2) webhooks, private domain webhooks, and per-inbox webhooks alike.
GET /v3/webhooks/deliveries - query
| Parameter | Type | Description |
|---|---|---|
| status | ?string | pending | success | failed |
| address / domain | ?string | Filter by recipient inbox or domain |
| limit / cursor | ?number / ?string | Pagination (max 200) |
/v3/inboxes/:token/webhookset webhook (Ultra)/v3/inboxes/:token/webhookread webhook/v3/inboxes/:token/webhookremove webhook/v3/webhooks/deliveriesdelivery log{
"deliveries": [{
"url": "https://example.com/hook",
"event": "email.received",
"address": "[email protected]",
"status": "success",
"attempt_count": 2,
"attempts": [
{ "at": "...", "status_code": 500, "error": "HTTP 500", "duration_ms": 12 },
{ "at": "...", "status_code": 200, "error": null, "duration_ms": 45 }
],
"created_at": "..."
}],
"next_cursor": null
}Custom Domains
Register a custom domain to your account, get the exact DNS records to create, and re-run verification whenever you like - with structured per-record results instead of a single pass/fail. Requires TempMail Plus or Ultra.
DNS records returned by the API
| Type | Name | Value |
|---|---|---|
| TXT | <hash>.yourdomain.com | tm-custom-domain-verification |
| A | mx.yourdomain.com | (returned by the API) |
| MX | yourdomain.com | mx.yourdomain.com (priority 10, must be the only MX) |
The exact TXT name/value pair is account-specific - always read it from the API response.
POST /v3/domains/verify re-checks up to 100 of your domains in one call, least recently checked first, and returns the same per-domain results. It can run once every 10 minutes per account; calling it sooner returns 429 rate_limited with a retry-after header.
/v3/domainslist your domains/v3/domainsregister + verify/v3/domains/:domaindetails + DNS records/v3/domains/:domain/verifyre-run verification/v3/domains/verifyre-verify all (once per 10 min)/v3/domains/:domainunregister{
"domain": { "domain": "yourdomain.com", "verified": true, ... },
"checks": {
"txt": { "pass": true, "detail": "Ownership TXT record found." },
"mx": { "pass": false, "records": [...],
"expected": "mx.yourdomain.com",
"detail": "Expected a single MX record..." }
},
"dns": { "ownership_txt_options": [...], "mail_records": [...] }
}TempMail Domains
List every domain TempMail itself serves, split into the premium pool that only Plus/Ultra accounts can create inboxes on and the free pool that any tier can use. Pass any of them as domain when creating an inbox. Requires TempMail Plus or Ultra and the domains:read scope; free accounts get a tier_required error.
Response fields
| Field | Type | Description |
|---|---|---|
| domains_premium | string[] | The premium pool. Random Plus/Ultra inboxes are drawn from here. |
| domains_free | string[] | The free pool, including community domains. Usable by every tier. |
An entry starting with *. is a wildcard: both the bare domain and any subdomain of it are accepted, so *.example.com lets you create [email protected] or [email protected]. The lists change over time as domains are rotated in and out, so re-fetch them rather than caching them for long.
/v3/domains/poollist TempMail domains (Plus/Ultra)curl https://api.tempmail.lol/v3/domains/pool \
-H "Authorization: Bearer tempmail.sk...."
{
"domains_premium": [
"*.plusonly.example",
"premium.example"
],
"domains_free": [
"*.free.example",
"community.example"
]
}Usage & Quota
See your tier, how much of the inbox-creation window you have used, and counts of your active inboxes, keys, and domains. Requires the usage:read scope.
{
"tier": "ultra",
"inbox_creation": {
"window_seconds": 300,
"limit": 5000,
"used": 2,
"remaining": 4998,
"resets_at": 1784161500000,
"limited_by": "account"
},
"inboxes_active": 2,
"api_keys_active": 1,
"custom_domains": 0,
"webhook_deliveries_last_7d": 14
}API 帮助
需要 API 帮助?加入我们的Discord 服务器!我们很乐意帮助您,如果您遇到问题或只是需要一些API方面的帮助,请告诉我们。