入门

欢迎使用 TempMail 开发者 API。我们有一些很棒的功能,例如...

  • 免费层级无需 API 密钥注册
  • Plus 和 Ultra 用户的自定义域
  • 还有更多!查看我们的 价格页面 了解更多信息。

如果不使用库,所有的POST请求必须将Content-Type头设置为application/json!

选择您的库

Python

NodeJS

Java

HTTP

$ pip3 install tempmail-lol

API 类型

邮件

一个邮件对象,当您检查您的收件箱时返回。

名称类型描述
fromstring邮件发送者
tostring接收者(您的临时邮箱)
subjectstring邮件主题
bodystring纯文本正文,可能为空
html?string邮件 HTML(可能为空)
datenumber接收邮件时的 Unix 时间戳

收件箱

一个收件箱对象,包含邮箱地址和访问令牌。

名称类型描述
addressstring创建的邮箱地址
tokenstring查看收件箱的访问令牌

收件箱生命周期

收件箱的生命周期取决于您的订阅层级。

订阅层级生命周期
免费(无订阅)一小时
TempMail Plus十小时
TempMail Ultra三十小时

收件箱生命周期可以通过重新请求创建收件箱方法延长(仅适用于自定义域)。

创建收件箱

创建收件箱方法可以使用 GET 或 POST。POST 方法允许您自定义选项,例如收件箱的前缀和域。

GET 方法目前仅存在于遗留原因。

POST /v2/inbox/create
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)

名称类型描述
addressstring收件箱的邮箱地址。
tokenstring收件箱的令牌。

获取邮件

使用创建邮箱时收到的令牌获取邮件。如果您丢失了令牌,您将无法再访问邮件,除非是自定义域(请不要为此联系支持,我们无法出于法律原因给您邮箱地址)。

GET /v2/inbox
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

查询

参数类型描述默认
tokenstring访问收件箱的令牌null

响应 (200)

名称类型描述
emailsEmail[]从服务器接收到的邮件数组
expiredboolean如果收件箱过期为真(见收件箱生命周期)

准备自定义域

在 TempMail 上使用自定义域之前,您必须设置一些记录。建议在账户页面进行,但您也可以通过 API 进行。

使用自定义域需要 TempMail Plus 或 Ultra 订阅。

POST /v2/custom

正文

参数类型描述默认
domainstring在 TempMail 上注册的域null

Response (200)

名称类型描述
uuidstring为您的域记录设置的 UUID(见下文)

在您的域下添加此记录为[uuid].yourdomain.com,并将值设置为tm-custom-domain-verification。

如果您使用子域,请设置为[uuid].subdomain.yourdomain.com。

响应 (4xx)

名称类型描述
errorstring解释为何无法设置域的错误。

创建自定义域地址

与创建普通收件箱的方式相同,使用您的域创建自定义域收件箱!

注意事项:

  • 必须使用创建域的UUID时使用的相同账户
  • prefix参数将设置为无前导数字的普通前缀
POST /v2/inbox/create
from TempMail import TempMail
tmp = TempMail("API Key required for custom domains")

inb = tmp.createInbox()

inb = tmp.createInbox(domain = "mycustomdomain.com", prefix = "optional")

正文

参数类型描述默认
domainstring您的自定义域。null
prefix?string收件箱的邮箱地址(@之前的部分),或随机。null

响应 (201)

名称类型描述
addressstring收件箱的邮箱地址。
tokenstring收件箱的令牌。

如果您丢失了收件箱的令牌,请使用相同的前缀再次调用该方法。收件箱的生命周期将根据您的订阅延长。您可以无限次延长。

使用获取邮件的方法检查收件箱。

私有 Webhooks

设置私有 webhooks,以便您域的所有邮件直接发送到您的 webhook。

需要有效的 TempMail Ultra 订阅。

您必须已经为自定义域设置好域([uuid].domain.com)。

POST /v2/private_webhook

Body

参数类型描述默认
domainstring设置 webhook 的域null
urlstring邮件将转发到的 webhook URLnull

响应 (200)

名称类型描述
successtrue总是为真
messagestring成功信息消息

响应 (4xx)

名称类型描述
errorstring包含错误详细信息的消息

您还可以使用域作为查询参数 DELETE /private_webhook 来删除它。

标准 Webhooks

在您创建的每个标准邮箱上设置标准 webhooks。邮件将转发到您的 webhook。

需要有效的 TempMail Ultra 订阅。

这不会追溯应用于现有邮件。

POST /v2/webhook

正文

参数类型描述默认
urlstring邮件将转发到的 webhook URLnull

响应 (200)

名称类型描述
successtrue总是为真

响应 (4xx)

名称类型描述
errorstring包含错误详细信息的消息

您还可以使用 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-remaining and x-ratelimit-reset headers (reset is a unix timestamp in seconds). 429 responses include retry-after.
  • v2 stays supported. Inboxes are shared between versions; v3 has its own create and fetch endpoints, but tokens work on both.
Base URL & authentication
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

ScopeGrants
inboxes:createCreate inboxes (works on v1/v2 create endpoints too)
inboxes:readList your inboxes
webhooks:readRead webhook config and delivery logs
webhooks:writeSet/remove per-inbox webhooks
domains:readList/inspect custom domains
domains:writeRegister/verify/remove custom domains
usage:readRead usage & quota
GET/v3/keyslist keys
POST/v3/keyscreate a key
PATCH/v3/keys/:idrename / re-scope / revoke
DELETE/v3/keys/:iddelete a key
POST /v3/keys
curl -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 now

Create & 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)

ParameterTypeDescriptionDefault
prefix?stringLocal part prefix (a-z, 0-9, _, -)random
domain?stringA 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?booleanPrefer a community domainfalse

GET /v3/inboxes - query

ParameterTypeDescriptionDefault
limit?numberPage size (max 200)50
cursor?stringnext_cursor from the previous pagenull
include_expired?booleanAlso return expired inboxesfalse
POST/v3/inboxescreate an inbox
GET/v3/inboxeslist your inboxes
GET/v3/inboxes/:tokenmetadata + email count
DELETE/v3/inboxes/:tokendelete inbox + its emails
POST /v3/inboxes
curl -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

ParameterTypeDescriptionDefault
since?numberOnly emails with date >= this unix ms timestamp0
limit?numberMax emails returned (max 200)100
GET/v3/inboxes/:token/emailsfetch + consume
DELETE/v3/inboxes/:token/emails/:iddelete without reading
GET/v3/inboxes/:token/emails/:id/rawdownload .eml (Ultra)
GET /v3/inboxes/:token/emails/:id/raw
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

ParameterTypeDescriptionDefault
timeout?numberSeconds to wait (max 60)30
from?stringSender filter, wildcards allowed (*@example.com)null
since?numberIgnore emails older than this unix ms timestamp0

At most 2 concurrent /wait requests per inbox. A timeout is still HTTP 200, with "timed_out": true and an empty emails array.

GET /v3/inboxes/:token/wait
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

ParameterTypeDescription
status?stringpending | success | failed
address / domain?stringFilter by recipient inbox or domain
limit / cursor?number / ?stringPagination (max 200)
PUT/v3/inboxes/:token/webhookset webhook (Ultra)
GET/v3/inboxes/:token/webhookread webhook
DELETE/v3/inboxes/:token/webhookremove webhook
GET/v3/webhooks/deliveriesdelivery log
GET /v3/webhooks/deliveries
{
  "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

TypeNameValue
TXT<hash>.yourdomain.comtm-custom-domain-verification
Amx.yourdomain.com(returned by the API)
MXyourdomain.commx.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.

GET/v3/domainslist your domains
POST/v3/domainsregister + verify
GET/v3/domains/:domaindetails + DNS records
POST/v3/domains/:domain/verifyre-run verification
POST/v3/domains/verifyre-verify all (once per 10 min)
DELETE/v3/domains/:domainunregister
POST /v3/domains/:domain/verify
{
  "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

FieldTypeDescription
domains_premiumstring[]The premium pool. Random Plus/Ultra inboxes are drawn from here.
domains_freestring[]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.

GET/v3/domains/poollist TempMail domains (Plus/Ultra)
GET /v3/domains/pool
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.

GET /v3/usage
{
  "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方面的帮助,请告诉我们。