Başlarken

TempMail Geliştirici API'sine hoş geldiniz. Harika özelliklerimiz var, örneğin...

  • Ücretsiz katman için API anahtarı gerektirmez
  • Plus ve Ultra kullanıcıları için özel alanlar
  • Ve çok daha fazlası! Daha fazla bilgi için fiyatlandırma sayfasına göz atın.

Kütüphane kullanmıyorsanız, tüm POST isteklerinde Content-Type başlığının application/json olarak ayarlanması gerekir!

Kütüphanenizi seçin

Python

NodeJS

Java

HTTP

$ pip3 install tempmail-lol

API Türleri

E-posta

Gelen kutunuzu kontrol ettiğinizde döndürülen bir e-posta nesnesi.

AdTürAçıklama
fromstringE-postanın göndericisi
tostringAlıcı (geçici e-postanız)
subjectstringE-postanın konusu
bodystringDüz metin gövdesi, boş olabilir
html?stringE-posta HTML'si (boş olabilir)
datenumberE-postanın alındığı Unix zaman damgası

Gelen Kutusu

Oluşturulan e-posta adresi ve erişim tokenini içeren bir gelen kutusu nesnesi.

AdTürAçıklama
addressstringOluşturulan e-posta adresi
tokenstringGelen kutusunu görüntülemek için kullanılan erişim tokeni

Gelen Kutusu Ömrü

Gelen kutuları, abonelik seviyenize bağlı olarak farklı ömre sahiptir.

Abonelik SeviyesiÖmür
Ücretsiz (abonelik yok)Bir Saat
TempMail PlusOn Saat
TempMail UltraOtuz Saat

Gelen kutusu ömrü, sadece özel alanlar için, gelen kutusu oluşturma yöntemini yeniden talep ederek uzatılabilir.

Gelen Kutusu Oluştur

Gelen Kutusu Oluştur yöntemi GET veya POST ile kullanılabilir. POST yöntemi, gelen kutusunun öneki ve alanı gibi seçenekleri özelleştirmenize olanak tanır.

GET yöntemi şu anda yalnızca eski nedenlerle mevcuttur.

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")

Gövde

ParametreTürAçıklamaVarsayılan
domain?stringGelen kutusunun alanı veya rastgele. Özel bir alan olabilir.null
prefix?stringGelen kutusunun öneki veya rastgele.null

Yanıt (201)

AdTürAçıklama
addressstringGelen kutusunun e-posta adresi.
tokenstringGelen kutusunun tokeni.

E-postaları Al

E-posta oluşturulduğunda alınan token kullanarak e-postaları al. Tokeninizi kaybederseniz, özel alan değilse, e-postaya erişim sağlayamazsınız (bu konuda destekle iletişime geçmeyin, yasal nedenlerle size e-posta adresini veremeyiz).

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

Sorgu

ParametreTürAçıklamaVarsayılan
tokenstringGelen kutusuna erişmek için kullanılan tokennull

Yanıt (200)

AdTürAçıklama
emailsEmail[]Sunucudan alınan e-postaların dizisi
expiredbooleanGelen kutusu süresi dolmuşsa true (bkz. gelen kutusu ömrü)

Özel Alan Hazırla

TempMail üzerinde özel bir alan kullanmadan önce birkaç kayıt ayarlamalısınız. Bunu Hesaplar Sayfasında yapmanız önerilir, ancak API üzerinden de yapabilirsiniz.

Özel alanlar, TempMail Plus veya Ultra aboneliği gerektirir.

POST /v2/custom

Gövde

ParametreTürAçıklamaVarsayılan
domainstringTempMail üzerinde kaydedilecek alannull

Response (200)

AdTürAçıklama
uuidstringAlan kaydınız için ayarlamanız gereken UUID (aşağıya bakın)

Alanınıza [uuid].yourdomain.com altında bu kaydı ekleyin ve değeri tm-custom-domain-verification. olarak ayarlayın.

Bir alt alan adı kullanıyorsanız, [uuid].subdomain.yourdomain.com. olarak ayarlayın.

Yanıt (4xx)

AdTürAçıklama
errorstringAlan kaydedilemediğinde açıklayan hata.

Özel Alan Adresi Oluştur

Normal gelen kutularını oluşturduğunuz şekilde özel alan gelen kutusu oluşturun, ancak alanınızla!

Notlar:

  • UUID'yi oluşturmak için kullanılan hesapla aynı hesabı kullanmalısınız
  • prefix parametresi, başında sayı olmayan normal öneki ayarlar
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")

Gövde

ParametreTürAçıklamaVarsayılan
domainstringÖzel alanınız.null
prefix?stringGelen kutusunun e-posta adresi (önce @) veya rastgele.null

Yanıt (201)

AdTürAçıklama
addressstringGelen kutusunun e-posta adresi.
tokenstringGelen kutusunun tokeni.

Gelen kutusunun tokenini kaybederseniz, aynı önekle yöntemi tekrar çağırın. Gelen kutusu ömrü aboneliğinize göre uzatılacaktır. Sonsuz kez uzatabilirsiniz.

Gelen kutusunu E-postaları Al yöntemiyle kontrol edin.

Özel Webhooks

Tüm e-postaların alanınıza yönlendirilmesi için özel webhooks ayarlayın.

Aktif bir TempMail Ultra aboneliği gerektirir.

Özel alanlar için alanınızı zaten ayarlamış olmalısınız ([uuid].domain.com).

POST /v2/private_webhook

Body

ParametreTürAçıklamaVarsayılan
domainstringWebhook'unuzu ayarlayacağınız alannull
urlstringE-postaların yönlendirileceği webhook URL'sinull

Yanıt (200)

AdTürAçıklama
successtrueHer zaman true
messagestringBaşarı bilgisi mesajı

Yanıt (4xx)

AdTürAçıklama
errorstringHata detaylarını içeren mesaj

Webhook'u kaldırmak için domain sorgu parametresi ile DELETE /private_webhook da yapabilirsiniz.

Standart Webhooks

Oluşturduğunuz her standart e-postada standart webhooks ayarlayın. E-postalar webhook'unuza yönlendirilir.

Aktif bir TempMail Ultra aboneliği gerektirir.

Bu mevcut e-postalara geriye dönük olarak uygulanmayacaktır.

POST /v2/webhook

Gövde

ParametreTürAçıklamaVarsayılan
urlstringE-postaların yönlendirileceği webhook URL'sinull

Yanıt (200)

AdTürAçıklama
successtrueHer zaman true

Yanıt (4xx)

AdTürAçıklama
errorstringHata detaylarını içeren mesaj

Hesabınızdan kaldırmak için DELETE /webhook da yapabilirsiniz.

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 Yardımı

API ile ilgili yardıma mı ihtiyacınız var? Discord Sunucumuza katılın! Bir sorununuz olduğunda veya API'mizle ilgili bir şeyleri anlamak için yardıma ihtiyacınız olduğunda bize bildirin, size yardımcı olmaktan mutluluk duyarız.