Начало Работы
Добро пожаловать в TempMail Developer API. У нас есть отличные функции, такие как...
- Не требуется регистрация API ключа (для бесплатного тарифа)
- Пользовательские домены для пользователей Plus и Ultra
- И многое другое! Ознакомьтесь с нашей страницей цен для получения дополнительной информации.
Если вы не используете библиотеку, все POST запросы должны иметь заголовок Content-Type, установленный на application/json!
Выберите вашу библиотеку

Python
NodeJS

Java
HTTP
$ pip3 install tempmail-lolТипы API
Объект email, который возвращается при проверке вашего почтового ящика.
| Имя | Тип | Описание |
|---|---|---|
| from | string | Отправитель письма |
| to | string | Получатель (ваш временный email) |
| subject | string | Тема письма |
| body | string | Текстовое тело, может быть пустым |
| html | ?string | HTML письма (может быть null) |
| date | number | UNIX timestamp, когда письмо было получено |
Почтовый ящик
Объект почтового ящика, содержащий email адрес и токен доступа.
| Имя | Тип | Описание |
|---|---|---|
| address | string | Email адрес, который был создан |
| 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 | Email адрес почтового ящика. |
| token | string | Токен почтового ящика. |
Получить Письма
Получите письма, используя токен, полученный при создании почтового ящика. Если вы потеряете свой токен, вы больше не сможете получить доступ к почтовому ящику, если это не пользовательский домен (пожалуйста, не обращайтесь в поддержку по этому поводу, мы не можем предоставить вам email адрес по юридическим причинам).
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 | True, если почтовый ящик истек (см. срок действия почтового ящика) |
Подготовка Пользовательского Домена
Прежде чем пользовательский домен можно будет использовать на 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 | Email адрес (перед @) почтового ящика, или случайный. | null |
Ответ (201)
| Имя | Тип | Описание |
|---|---|---|
| address | string | Email адрес почтового ящика. |
| token | string | Токен почтового ящика. |
Если вы потеряете токен почтового ящика, вызовите метод снова с тем же префиксом. Срок действия почтового ящика будет продлен в зависимости от вашей подписки. Вы можете продлевать бесконечное количество раз.
Проверьте почтовый ящик, используя метод в Получить Письма.
Частные Webhooks
Настройте частные webhooks так, чтобы все письма для вашего домена направлялись на ваш webhook.
Требуется активная подписка TempMail Ultra.
Вы должны уже настроить ваш домен для пользовательских доменов ([uuid].domain.com).
Body
| Параметр | Тип | Описание | По умолчанию |
|---|---|---|---|
| domain | string | Домен для настройки вашего webhook | null |
| url | string | URL webhook, на который будут пересылаться письма | null |
Ответ (200)
| Имя | Тип | Описание |
|---|---|---|
| success | true | Всегда true |
| message | string | Информационное сообщение об успехе |
Ответ (4xx)
| Имя | Тип | Описание |
|---|---|---|
| error | string | Сообщение с подробностями об ошибке |
Вы также можете удалить /private_webhook с доменом в качестве параметра запроса для его удаления.
Стандартные Webhooks
Настройте стандартные webhooks на каждый стандартный email, который вы создаете. Письма будут пересылаться на ваш webhook.
Требуется активная подписка TempMail Ultra.
Это не будет применяться к уже существующим email.
Тело
| Параметр | Тип | Описание | По умолчанию |
|---|---|---|---|
| url | string | URL webhook, на который будут пересылаться письма | null |
Ответ (200)
| Имя | Тип | Описание |
|---|---|---|
| success | true | Всегда 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-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.