API v2

เริ่มต้นใช้งาน ประเภท API สร้างกล่องขาเข้า ดึงอีเมล เตรียมโดเมนที่กำหนดเอง สร้างที่อยู่โดเมนที่กำหนดเอง Private Webhooks Standard Webhooks

API v3 NEW

v3 Overview Scoped API Keys Create & Manage Inboxes Emails & Raw .eml Wait for Email Webhooks & Deliveries Custom Domains TempMail Domains Usage & Quota

เริ่มต้นใช้งาน

ยินดีต้อนรับสู่ TempMail Developer API เรามีฟีเจอร์ที่ยอดเยี่ยม เช่น...

ไม่ต้องลงทะเบียน API key (สำหรับระดับฟรี)
โดเมนที่กำหนดเองสำหรับผู้ใช้ Plus และ Ultra
และอีกมากมาย! ตรวจสอบ หน้าราคา สำหรับข้อมูลเพิ่มเติม

หากไม่ใช้ไลบรารี, คำขอ POST ทั้งหมดต้องมีส่วนหัว Content-Type ตั้งค่าเป็น application/json!

เลือกไลบรารีของคุณ

Python

NodeJS

Java

HTTP

$ pip3 install tempmail-lol

ประเภท API

อีเมล

วัตถุอีเมลที่ถูกส่งกลับเมื่อคุณตรวจสอบกล่องขาเข้า

ชื่อ	ประเภท	คำอธิบาย
from	string	ผู้ส่งอีเมล
to	string	ผู้รับ (อีเมลชั่วคราวของคุณ)
subject	string	หัวข้อของอีเมล
body	string	เนื้อหาแบบตัวอักษร, อาจว่างเปล่า
html	?string	HTML ของอีเมล (อาจเป็น null)
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	จริงหากกล่องขาเข้าหมดอายุ (ดูอายุการใช้งานของกล่องขาเข้า)

เตรียมโดเมนที่กำหนดเอง

ก่อนที่โดเมนที่กำหนดเองจะสามารถใช้ได้บน TempMail คุณต้องตั้งค่าระเบียนไม่กี่รายการ แนะนำให้ทำที่ หน้าบัญชี แต่คุณสามารถทำผ่าน API ได้เช่นกัน

โดเมนที่กำหนดเองต้องการการสมัครสมาชิก TempMail Plus หรือ Ultra

เนื้อหา

พารามิเตอร์	ประเภท	คำอธิบาย	ค่าเริ่มต้น
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	โทเค็นของกล่องขาเข้า

หากคุณสูญเสียโทเค็นของกล่องขาเข้า เรียกใช้วิธีนี้อีกครั้งด้วยคำนำหน้าเดียวกัน อายุการใช้งานของกล่องขาเข้าจะถูกขยายตามการสมัครสมาชิกของคุณ คุณสามารถขยายได้ไม่จำกัด

ตรวจสอบกล่องขาเข้าด้วยวิธีในดึงอีเมล

Private Webhooks

ตั้งค่า private webhooks เพื่อให้ทุกอีเมลสำหรับโดเมนของคุณส่งไปยัง webhook ของคุณ

ต้องการการสมัครสมาชิก TempMail Ultra ที่ใช้งานอยู่

คุณต้องตั้งค่าโดเมนของคุณสำหรับโดเมนที่กำหนดเองแล้ว ([uuid].domain.com)

Body

พารามิเตอร์	ประเภท	คำอธิบาย	ค่าเริ่มต้น
domain	string	โดเมนที่จะตั้งค่า webhook ของคุณ	null
url	string	URL ของ webhook ที่อีเมลจะถูกส่งต่อไป	null

การตอบกลับ (200)

ชื่อ	ประเภท	คำอธิบาย
success	true	เสมอจริง
message	string	ข้อความข้อมูลความสำเร็จ

การตอบกลับ (4xx)

ชื่อ	ประเภท	คำอธิบาย
error	string	ข้อความที่มีรายละเอียดเกี่ยวกับข้อผิดพลาด

คุณยังสามารถลบ /private_webhook ด้วยโดเมนเป็นพารามิเตอร์คำถามเพื่อลบมัน

Standard Webhooks

ตั้งค่า standard webhooks บนอีเมลมาตรฐานทุกฉบับที่คุณสร้าง อีเมลจะถูกส่งต่อไปยัง webhook ของคุณ

ต้องการการสมัครสมาชิก TempMail Ultra ที่ใช้งานอยู่

สิ่งนี้จะไม่ถูกใช้ย้อนกลับไปยังอีเมลที่มีอยู่

เนื้อหา

พารามิเตอร์	ประเภท	คำอธิบาย	ค่าเริ่มต้น
url	string	URL ของ webhook ที่อีเมลจะถูกส่งต่อไป	null

การตอบกลับ (200)

ชื่อ	ประเภท	คำอธิบาย
success	true	เสมอจริง

การตอบกลับ (4xx)

ชื่อ	ประเภท	คำอธิบาย
error	string	ข้อความที่มีรายละเอียดเกี่ยวกับข้อผิดพลาด

คุณยังสามารถลบ /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:  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

GET/v3/keyslist keys

POST/v3/keyscreate a key

PATCH/v3/keys/:idrename / re-scope / revoke

DELETE/v3/keys/:iddelete a key

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)

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

POST/v3/inboxescreate an inbox

GET/v3/inboxeslist your inboxes

GET/v3/inboxes/:tokenmetadata + email count

DELETE/v3/inboxes/:tokendelete inbox + its emails

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

Parameter	Type	Description	Default
since	?number	Only emails with `date >=` this unix ms timestamp	0
limit	?number	Max 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)

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)

PUT/v3/inboxes/:token/webhookset webhook (Ultra)

GET/v3/inboxes/:token/webhookread webhook

DELETE/v3/inboxes/:token/webhookremove webhook

GET/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.

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

{
  "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.

GET/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 Server ของเรา! เรายินดีที่จะช่วยเหลือ แจ้งให้เราทราบหากคุณมีปัญหา หรือถ้าคุณต้องการความช่วยเหลือในการทำความเข้าใจเกี่ยวกับ API ของเรา