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-lolAPI Türleri
E-posta
Gelen kutunuzu kontrol ettiğinizde döndürülen bir e-posta nesnesi.
| Ad | Tür | Açıklama |
|---|---|---|
| from | string | E-postanın göndericisi |
| to | string | Alıcı (geçici e-postanız) |
| subject | string | E-postanın konusu |
| body | string | Düz metin gövdesi, boş olabilir |
| html | ?string | E-posta HTML'si (boş olabilir) |
| date | number | E-postanın alındığı Unix zaman damgası |
Gelen Kutusu
Oluşturulan e-posta adresi ve erişim tokenini içeren bir gelen kutusu nesnesi.
| Ad | Tür | Açıklama |
|---|---|---|
| address | string | Oluşturulan e-posta adresi |
| token | string | Gelen 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 Plus | On Saat |
| TempMail Ultra | Otuz 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.
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
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| domain | ?string | Gelen kutusunun alanı veya rastgele. Özel bir alan olabilir. | null |
| prefix | ?string | Gelen kutusunun öneki veya rastgele. | null |
Yanıt (201)
| Ad | Tür | Açıklama |
|---|---|---|
| address | string | Gelen kutusunun e-posta adresi. |
| token | string | Gelen 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).
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
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| token | string | Gelen kutusuna erişmek için kullanılan token | null |
Yanıt (200)
| Ad | Tür | Açıklama |
|---|---|---|
| emails | Email[] | Sunucudan alınan e-postaların dizisi |
| expired | boolean | Gelen 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.
Gövde
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| domain | string | TempMail üzerinde kaydedilecek alan | null |
Response (200)
| Ad | Tür | Açıklama |
|---|---|---|
| uuid | string | Alan 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)
| Ad | Tür | Açıklama |
|---|---|---|
| error | string | Alan 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
prefixparametresi, başında sayı olmayan normal öneki ayarlar
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
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| domain | string | Özel alanınız. | null |
| prefix | ?string | Gelen kutusunun e-posta adresi (önce @) veya rastgele. | null |
Yanıt (201)
| Ad | Tür | Açıklama |
|---|---|---|
| address | string | Gelen kutusunun e-posta adresi. |
| token | string | Gelen 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).
Body
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| domain | string | Webhook'unuzu ayarlayacağınız alan | null |
| url | string | E-postaların yönlendirileceği webhook URL'si | null |
Yanıt (200)
| Ad | Tür | Açıklama |
|---|---|---|
| success | true | Her zaman true |
| message | string | Başarı bilgisi mesajı |
Yanıt (4xx)
| Ad | Tür | Açıklama |
|---|---|---|
| error | string | Hata 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.
Gövde
| Parametre | Tür | Açıklama | Varsayılan |
|---|---|---|---|
| url | string | E-postaların yönlendirileceği webhook URL'si | null |
Yanıt (200)
| Ad | Tür | Açıklama |
|---|---|---|
| success | true | Her zaman true |
Yanıt (4xx)
| Ad | Tür | Açıklama |
|---|---|---|
| error | string | Hata 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-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 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.