Список быстрой настройки
- Откройте страницу управления API в своей панели управления и создайте свой личный ключ API.
- Скопируйте точный базовый URL API пользователя, показанный там, например https://v1.tempmailg.com/api.
- Отправляйте каждый запрос на этот хост API с Authorization: Bearer YOUR_USER_API_KEY и Accept: application/json.
- Отслеживайте свою ежемесячную квоту запросов на той же странице панели управления и в заголовках квоты, когда они доступны в ответах пользовательского API. Только успешные запросы с кодом 2xx учитываются в квоте.
Доступ по ключу API
Войдите, чтобы создать личный ключ API и просмотреть подробности живой квоты.
Поток аутентификации
- Сгенерируйте личный ключ API со страницы управления API в панели управления.
- Отправьте ключ в качестве токена Bearer в каждый запрос.
- Используйте специальный базовый URL API пользователя, показанный на вашей странице управления API.
- Регенерируйте ключ всякий раз, когда вы хотите аннулировать старый и начать использовать новый ключ сразу же.
Обязательные заголовки
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
Заголовки ограничения скорости и квоты
Заголовки ограничения скорости описывают указанный бюджет запросов. Заголовки квоты включаются, когда доступна информация о квоте; отклонения по минутному лимиту не учитывают вашу полную месячную квоту.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1729520000
X-Quota-Limit: 50000
X-Quota-Remaining: 48210
X-Quota-Used: 1790
X-Quota-Reset: 2026-11-01T00:00:00+00:00
X-RateLimit-Scope: account
Retry-After: 42 (when a timed retry is available)
X-RateLimit-Limit— Максимальное количество запросов, разрешённых в минуту (RPM) для вашего плана.X-RateLimit-Remaining— Оставшиеся запросы RPM в текущем минутном окне.X-RateLimit-Reset— Unix метка времени, когда сбрасывается текущий минутный лимит скорости.X-Quota-Limit— Общая ежемесячная и приобретённая кредитная емкость вашего аккаунта.X-Quota-Remaining— Оставшееся количество доступных запросов API в текущем месяце.X-Quota-Used— Общее количество запросов API, использованных за текущий расчетный период.X-Quota-Reset— ISO-8601 метка времени, когда сбрасывается ваша месячная квота.X-RateLimit-Scope— Бюджет, описанный заголовками: account, ip, status_endpoint или mailbox.X-Mailbox-RateLimit-*— Отдельный бюджет создания/обновления почтового ящика. Успешные ответы почтового ящика сохраняют RPM аккаунта в X-RateLimit-*; отклонение, касающееся только почтового ящика, использует область почтового ящика и собственное окно повторных попыток.Retry-After— Секунды до того, как будет уместна повторная попытка по таймеру. Отключённый план или исчерпанная квота могут потребовать смену аккаунта, поэтому этот заголовок не всегда присутствует.503 protection_unavailable— Хранилище или координация защиты API временно недоступны. Повторите попытку позже; это не ошибка оплаты и не списание кредита.
Управление почтовым ящиком
Получайте разрешённые домены, создавайте или переключайте почтовые ящики, выбирайте разрешённые сроки действия и удаляйте принадлежащие адреса.
Список разрешённых доменов
Список доступных доменов для создания временных электронных писем. Фильтруйте по типу, чтобы увидеть только бесплатные, премиум или пользовательские домены, поддерживаемые вашим планом подписки.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
type
|
query | string | необязательно |
Фильтр уровня домена. При отсутствии указания используется все, когда доступ к премиум-домену включён, иначе — бесплатный. Распознаваемые значения: free, basic, pro, premium, custom, ultimate, all
По умолчанию:
Зависит от учетной записи
|
const response = await fetch('https://v1.tempmailg.com/api/domains?type=free', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/domains?type=free', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/domains?type=free');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/domains?type=free' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"requested_type": "free",
"plan": "pro",
"plan_name": "Pro Plan",
"allowed_types": [
"free",
"basic",
"pro",
"premium",
"custom",
"ultimate",
"all"
],
"domains": [
{
"domain": "example.com",
"type": "Free",
"custom": false
}
]
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.requested_type |
string | Применён фильтр домена. |
data.plan |
string | Текущий тег плана. |
data.plan_name |
string | Читаемое название текущего плана. |
data.allowed_types |
array<string> | Фильтры доменов, доступные для этой учётной записи. Признанный фильтр всё ещё может быть запрещён в вашем тарифе. |
data.domains |
array | Выбираемые домены после фильтрации; пустой массив считается допустимым. |
data.domains[].domain |
string | Выбираемое доменное имя. |
data.domains[].type |
string | Метка уровня читаемого домена. |
data.domains[].custom |
boolean | Является ли это пользовательским доменом. |
Создать временный почтовый ящик
Создайте собственный временный почтовый ящик. Оставьте имя пользователя и домен пустыми для случайной генерации, либо укажите разрешённое пользовательское имя и допустимый домен. Параметр provider может выбирать генерацию псевдонима Gmail или Outlook.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
username
|
body | string | необязательно |
Опциональное пользовательское имя: от 2 до 64 символов ASCII, включая буквы, цифры, точки, подчёркивания или дефисы. Требуется разрешение плана; также принимается custom_username.
По умолчанию:
Сгенерировано случайным образом
|
domain
|
body | string | необязательно |
Один из разрешённых доменов, возвращаемый GET /domains. При отсутствии выбора выбирается случайный разрешённый домен.
По умолчанию:
Случайный разрешённый домен
|
lifetime
|
body | string | необязательно |
разрешённые значения:
10m — 10 минут
1h — 1 час
2h — 2 Часа
1d — 1 сутки
1w — 1 Неделя
1m — 30 дней
3m — 90 дней
6m — 180 дней
1y — 365 дней
unlimited — Неограниченно
По умолчанию:
Срок действия плана по умолчанию
|
provider
|
body | string | необязательно |
Провайдер почтового ящика: standard, gmail_alias или outlook_alias.
По умолчанию:
standard
|
pin_enabled
|
body | boolean | необязательно |
Опциональная защита PIN для нового почтового ящика, если это разрешено вашим планом. Это не меняет PIN существующего почтового ящика.
По умолчанию:
false
|
pin
|
body | string | необязательно |
Требуется, когда pin_enabled равно true: PIN из 6‑8 цифр, отправляемый как строка, чтобы сохранить ведущие нули.
|
pin_confirmation
|
body | string | необязательно |
Требуется, когда pin_enabled равно true. Должно точно соответствовать pin.
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
username (пользовательское имя, если разрешено планом), domain (разрешённый домен, например example.com), lifetime (разрешённые значения: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). Опустите срок жизни или оставьте его пустым, чтобы использовать Срок жизни письма по умолчанию, настроенный для вашего текущего ежемесячного/годового плана. Укажите разрешённый срок жизни, например 1h, чтобы переопределить значение по умолчанию. Неограниченный срок используется только когда он настроен как значение по умолчанию плана или явно запрошен и разрешён. Параметры тела mailbox_lifetime и email_lifetime также принимаются; первое непустое значение выигрывает в следующем порядке: lifetime, mailbox_lifetime, email_lifetime. Недопустимые или запрещённые значения возвращают HTTP 422 вместо того, чтобы молча выбирать значение по умолчанию.const response = await fetch('https://v1.tempmailg.com/api/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"id": 2301,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-20T02:18:08+00:00",
"expires_in_seconds": 86399.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:08+00:00",
"email_token": "encrypted-email-token"
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.id |
integer | Идентификатор почтового ящика. Сгенерированные идентификаторы, адреса и токены различаются для каждого ящика. |
data.pin_protected |
boolean | Указывает, защищён ли этот почтовый ящик PIN‑кодом. PIN или хеш PIN не возвращаются. |
data.email |
string | Сгенерирован полный адрес почтового ящика. |
data.domain |
string | Домен сгенерированного почтового ящика. |
data.provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
data.expire_at |
string|null | Эффективный срок истечения в виде метки времени ISO-8601, или null для неограниченного почтового ящика. |
data.expires_in_seconds |
number|null | Неотрицательное количество оставшихся секунд при расчёте; возможны дробные секунды. Null означает неограниченно, а не ноль. |
data.mailbox_state |
string | Текущее состояние почтового ящика: активно, приостановлено, истекло или неактивно. |
data.receiving_enabled |
boolean | Принимает ли этот почтовый ящик в настоящее время входящие сообщения. |
data.message_count |
integer | Известное общее количество сообщений; может отражать последнюю синхронизацию почтового ящика. |
data.unread_message_count |
integer | Известное количество непрочитанных сообщений; оно может отражать последнюю синхронизацию почтового ящика. |
data.last_message_received_at |
string|null | Последнее известное время получения сообщения в формате ISO-8601, или null, если недоступно. |
data.message_count_synced_at |
string|null | Время последней синхронизации количества сообщений в формате ISO-8601, или null до синхронизации. |
data.created_at |
string|null | Время создания почтового ящика в формате ISO-8601. |
data.email_token |
string | Непрозрачная зашифрованная ссылка на почтовый ящик. Она не заменяет аутентификацию Bearer, проверки прав собственности или авторизацию PIN. |
data.pin_grant |
object | Условно: при активном создании почтового ящика, защищённого PIN-кодом, возвращается это разрешение на чтение; обычное создание без защиты его не включает. |
data.pin_grant.mailbox_id |
integer | Идентификатор почтового ящика, к которому привязан условный грант на чтение. |
data.pin_grant.unlock_token |
string | Непрозрачный токен чтения для X-Mailbox-Unlock с теми же учётными данными владельца. Храните его в частном порядке и в памяти; предоставление прав чтения не даёт права на удаление. |
data.pin_grant.scope |
string | Область чтения для условного гранта создания. |
data.pin_grant.idle_timeout_seconds |
integer | Разрешённое время простоя для прав чтения, обычно 3600 секунд. |
data.pin_grant.absolute_timeout_seconds |
integer | Максимальное время жизни разрешения на чтение, обычно 86400 секунд. |
data.pin_grant.expires_at |
string | Текущий срок действия прав чтения в формате ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Абсолютный срок действия предоставления прав чтения в формате ISO-8601. Изменения в безопасности могут отозвать предоставление раньше. |
Обновить / Сменить почтовый ящик
Создайте или выберите почтовый ящик с новым именем пользователя и доменом после подтверждения владения текущим почтовым ящиком. Это не переименовывает старый почтовый ящик и не изменяет его срок действия на месте. Когда назначение отличается, старый почтовый ящик остаётся в истории и может быть приостановлен ограничениями активных почтовых ящиков. Повторное использование вашего собственного активного назначения повторно применяет запрошенный срок действия или значение по умолчанию плана.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
email
|
path | string | обязательно |
Текущий полный адрес электронной почты принадлежащего почтового ящика для переключения. URL‑кодируйте каждый сегмент пути; кодируйте знак плюс как %2B.
|
username
|
path | string | обязательно |
Новое желаемое имя пользователя: от 2 до 64 буквенно-цифровых символов; подлежит разрешению на пользовательские имена.
|
domain
|
path | string | обязательно |
Новое разрешённое доменное имя.
|
lifetime
|
body | string | необязательно |
разрешённые значения:
10m — 10 минут
1h — 1 час
2h — 2 Часа
1d — 1 сутки
1w — 1 Неделя
1m — 30 дней
3m — 90 дней
6m — 180 дней
1y — 365 дней
unlimited — Неограниченно
По умолчанию:
Срок действия плана по умолчанию
|
pin_enabled
|
body | boolean | необязательно |
Опциональная защита PIN для нового почтового ящика, если это разрешено вашим планом. Это не меняет PIN существующего почтового ящика.
По умолчанию:
false
|
pin
|
body | string | необязательно |
Требуется, когда pin_enabled равно true: PIN из 6‑8 цифр, отправляемый как строка, чтобы сохранить ведущие нули.
|
pin_confirmation
|
body | string | необязательно |
Требуется, когда pin_enabled равно true. Должно точно соответствовать pin.
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте read unlock_token. Сначала выполните POST pin и scope=read к PIN unlock URL. Сохраняйте обычную Bearer authentication. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime (разрешённые значения: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Опустите срок жизни или оставьте его пустым, чтобы использовать Срок жизни письма по умолчанию, настроенный для вашего текущего ежемесячного/годового плана. Укажите разрешённый срок жизни, например 1h, чтобы переопределить значение по умолчанию. Неограниченный срок используется только когда он настроен как значение по умолчанию плана или явно запрошен и разрешён. Параметры тела mailbox_lifetime и email_lifetime также принимаются; первое непустое значение выигрывает в следующем порядке: lifetime, mailbox_lifetime, email_lifetime. Недопустимые или запрещённые значения возвращают HTTP 422 вместо того, чтобы молча выбирать значение по умолчанию.const response = await fetch('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"id": 2302,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-19T02:28:08+00:00",
"expires_in_seconds": 599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:08+00:00",
"email_token": "encrypted-email-token"
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.id |
integer | Идентификатор почтового ящика. Сгенерированные идентификаторы, адреса и токены различаются для каждого ящика. |
data.pin_protected |
boolean | Указывает, защищён ли этот почтовый ящик PIN‑кодом. PIN или хеш PIN не возвращаются. |
data.email |
string | Сгенерирован полный адрес почтового ящика. |
data.domain |
string | Домен сгенерированного почтового ящика. |
data.provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
data.expire_at |
string|null | Эффективный срок истечения в виде метки времени ISO-8601, или null для неограниченного почтового ящика. |
data.expires_in_seconds |
number|null | Неотрицательное количество оставшихся секунд при расчёте; возможны дробные секунды. Null означает неограниченно, а не ноль. |
data.mailbox_state |
string | Текущее состояние почтового ящика: активно, приостановлено, истекло или неактивно. |
data.receiving_enabled |
boolean | Принимает ли этот почтовый ящик в настоящее время входящие сообщения. |
data.message_count |
integer | Известное общее количество сообщений; может отражать последнюю синхронизацию почтового ящика. |
data.unread_message_count |
integer | Известное количество непрочитанных сообщений; оно может отражать последнюю синхронизацию почтового ящика. |
data.last_message_received_at |
string|null | Последнее известное время получения сообщения в формате ISO-8601, или null, если недоступно. |
data.message_count_synced_at |
string|null | Время последней синхронизации количества сообщений в формате ISO-8601, или null до синхронизации. |
data.created_at |
string|null | Время создания почтового ящика в формате ISO-8601. |
data.email_token |
string | Непрозрачная зашифрованная ссылка на почтовый ящик. Она не заменяет аутентификацию Bearer, проверки прав собственности или авторизацию PIN. |
data.pin_grant |
object | Условно: при активном создании почтового ящика, защищённого PIN-кодом, возвращается это разрешение на чтение; обычное создание без защиты его не включает. |
data.pin_grant.mailbox_id |
integer | Идентификатор почтового ящика, к которому привязан условный грант на чтение. |
data.pin_grant.unlock_token |
string | Непрозрачный токен чтения для X-Mailbox-Unlock с теми же учётными данными владельца. Храните его в частном порядке и в памяти; предоставление прав чтения не даёт права на удаление. |
data.pin_grant.scope |
string | Область чтения для условного гранта создания. |
data.pin_grant.idle_timeout_seconds |
integer | Разрешённое время простоя для прав чтения, обычно 3600 секунд. |
data.pin_grant.absolute_timeout_seconds |
integer | Максимальное время жизни разрешения на чтение, обычно 86400 секунд. |
data.pin_grant.expires_at |
string | Текущий срок действия прав чтения в формате ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Абсолютный срок действия предоставления прав чтения в формате ISO-8601. Изменения в безопасности могут отозвать предоставление раньше. |
Удалить почтовый ящик
Удалить принадлежащий почтовый ящик и вызвать очистку его сообщений и файлов. Сохранённые записи почтового ящика могут быть мягко удалены внутри; адрес больше недоступен через API.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
email
|
path | string | обязательно |
Полный адрес электронной почты принадлежащего ящика, который нужно удалить. URL‑закодируйте адрес; знак плюс закодируйте как %2B.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте одноразовый токен разблокировки delete unlock_token. Сначала выполните POST pin, scope=delete и action/target_id, возвращённые в ответе 423 на URL разблокировки PIN. Токен чтения не может удалять. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
const response = await fetch('https://v1.tempmailg.com/api/emails/demo123@example.com', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/emails/demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/emails/demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
message |
string | Результат удаления. Отсутствующий ресурс возвращает HTTP 404. |
Псевдонимы Gmail и Outlook
Создайте почтовые ящики‑алиасы Gmail и Outlook/Hotmail с высокой репутацией.
Создать псевдоним Gmail
Создать новый временный почтовый ящик‑алиас Gmail, принадлежащий аутентифицированному пользователю.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
mode
|
body | string | необязательно |
Режим генерации: auto, dot, plus или plus_dot. Также поддерживается gmail_alias_mode. Если выбор стиля не разрешён, используется auto.
По умолчанию:
auto
|
username
|
body | string | необязательно |
Опциональный пользовательский суффикс псевдонима: от 2 до 32 символов ASCII (буквы или цифры), преобразованные в нижний регистр; зависит от разрешения функции. Также принимаются custom_username или alias_username.
По умолчанию:
Автогенерировано
|
domain
|
body | string | необязательно |
Используйте random, gmail.com или googlemail.com; также принимается alias_domain. При отсутствии или недоступном разрешении выбора домена используется random.
По умолчанию:
random
|
lifetime
|
body | string | необязательно |
разрешённые значения:
10m — 10 минут
1h — 1 час
2h — 2 Часа
1d — 1 сутки
1w — 1 Неделя
1m — 30 дней
3m — 90 дней
6m — 180 дней
1y — 365 дней
unlimited — Неограниченно
По умолчанию:
Срок действия плана по умолчанию
|
pin_enabled
|
body | boolean | необязательно |
Опциональная защита PIN для нового почтового ящика, если это разрешено вашим планом. Это не меняет PIN существующего почтового ящика.
По умолчанию:
false
|
pin
|
body | string | необязательно |
Требуется, когда pin_enabled равно true: PIN из 6‑8 цифр, отправляемый как строка, чтобы сохранить ведущие нули.
|
pin_confirmation
|
body | string | необязательно |
Требуется, когда pin_enabled равно true. Должно точно соответствовать pin.
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
mode (auto, dot, plus, plus_dot), username (пользовательское имя псевдонима), domain (например, gmail.com, googlemail.com), lifetime (разрешённые значения: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Опустите срок жизни или оставьте его пустым, чтобы использовать Срок жизни письма по умолчанию, настроенный для вашего текущего ежемесячного/годового плана. Укажите разрешённый срок жизни, например 1h, чтобы переопределить значение по умолчанию. Неограниченный срок используется только когда он настроен как значение по умолчанию плана или явно запрошен и разрешён. Параметры тела mailbox_lifetime и email_lifetime также принимаются; первое непустое значение выигрывает в следующем порядке: lifetime, mailbox_lifetime, email_lifetime. Недопустимые или запрещённые значения возвращают HTTP 422 вместо того, чтобы молча выбирать значение по умолчанию.const response = await fetch('https://v1.tempmailg.com/api/gmail-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/gmail-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/gmail-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/gmail-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"id": 2305,
"pin_protected": false,
"email": "example+alias123@gmail.com",
"domain": "gmail.com",
"provider": "gmail_alias",
"expire_at": "2026-11-19T03:18:08+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:08+00:00",
"email_token": "encrypted-email-token"
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.id |
integer | Идентификатор почтового ящика. Сгенерированные идентификаторы, адреса и токены различаются для каждого ящика. |
data.pin_protected |
boolean | Указывает, защищён ли этот почтовый ящик PIN‑кодом. PIN или хеш PIN не возвращаются. |
data.email |
string | Сгенерирован полный адрес почтового ящика. |
data.domain |
string | Домен сгенерированного почтового ящика. |
data.provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
data.expire_at |
string|null | Эффективный срок истечения в виде метки времени ISO-8601, или null для неограниченного почтового ящика. |
data.expires_in_seconds |
number|null | Неотрицательное количество оставшихся секунд при расчёте; возможны дробные секунды. Null означает неограниченно, а не ноль. |
data.mailbox_state |
string | Текущее состояние почтового ящика: активно, приостановлено, истекло или неактивно. |
data.receiving_enabled |
boolean | Принимает ли этот почтовый ящик в настоящее время входящие сообщения. |
data.message_count |
integer | Известное общее количество сообщений; может отражать последнюю синхронизацию почтового ящика. |
data.unread_message_count |
integer | Известное количество непрочитанных сообщений; оно может отражать последнюю синхронизацию почтового ящика. |
data.last_message_received_at |
string|null | Последнее известное время получения сообщения в формате ISO-8601, или null, если недоступно. |
data.message_count_synced_at |
string|null | Время последней синхронизации количества сообщений в формате ISO-8601, или null до синхронизации. |
data.created_at |
string|null | Время создания почтового ящика в формате ISO-8601. |
data.email_token |
string | Непрозрачная зашифрованная ссылка на почтовый ящик. Она не заменяет аутентификацию Bearer, проверки прав собственности или авторизацию PIN. |
data.pin_grant |
object | Условно: при активном создании почтового ящика, защищённого PIN-кодом, возвращается это разрешение на чтение; обычное создание без защиты его не включает. |
data.pin_grant.mailbox_id |
integer | Идентификатор почтового ящика, к которому привязан условный грант на чтение. |
data.pin_grant.unlock_token |
string | Непрозрачный токен чтения для X-Mailbox-Unlock с теми же учётными данными владельца. Храните его в частном порядке и в памяти; предоставление прав чтения не даёт права на удаление. |
data.pin_grant.scope |
string | Область чтения для условного гранта создания. |
data.pin_grant.idle_timeout_seconds |
integer | Разрешённое время простоя для прав чтения, обычно 3600 секунд. |
data.pin_grant.absolute_timeout_seconds |
integer | Максимальное время жизни разрешения на чтение, обычно 86400 секунд. |
data.pin_grant.expires_at |
string | Текущий срок действия прав чтения в формате ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Абсолютный срок действия предоставления прав чтения в формате ISO-8601. Изменения в безопасности могут отозвать предоставление раньше. |
Псевдонимные домены Outlook
Получить активные домены псевдонимов Outlook / Hotmail, доступные для создания почтового ящика.
const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/domains', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/outlook-alias/domains', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/domains');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/outlook-alias/domains' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"domains": [
{
"domain": "outlook.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
},
{
"domain": "hotmail.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
}
]
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.domains |
array | Активные домены Outlook/Hotmail; пустой массив допустим. |
data.domains[].domain |
string | Доступное доменное имя. |
data.domains[].type |
string | Читаемая метка поставщика. |
data.domains[].selectable |
boolean | Может ли ваша учётная запись явно выбрать этот домен. |
data.domains[].locked |
boolean | Заблокирован ли явный выбор домена для вашей учётной записи. |
data.domains[].disabled_reason |
string|null | Причина, по которой выбор домена заблокирован, или null, когда выбор возможен. |
Создать псевдоним Outlook
Создать новый временный почтовый ящик‑алиас Outlook / Hotmail, принадлежащий аутентифицированному пользователю.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
domain
|
body | string | необязательно |
Используйте случайный домен или домен из GET /outlook-alias/domains; также принимается outlook_alias_domain. Если нет разрешения на выбор, используется случайный.
По умолчанию:
Случайный доступный домен
|
username
|
body | string | необязательно |
Опциональный пользовательский суффикс псевдонима: от 2 до 32 символов ASCII (буквы или цифры), преобразованные в нижний регистр; зависит от разрешения функции. Также принимаются custom_username или alias_username.
По умолчанию:
Автогенерировано
|
lifetime
|
body | string | необязательно |
разрешённые значения:
10m — 10 минут
1h — 1 час
2h — 2 Часа
1d — 1 сутки
1w — 1 Неделя
1m — 30 дней
3m — 90 дней
6m — 180 дней
1y — 365 дней
unlimited — Неограниченно
По умолчанию:
Срок действия плана по умолчанию
|
pin_enabled
|
body | boolean | необязательно |
Опциональная защита PIN для нового почтового ящика, если это разрешено вашим планом. Это не меняет PIN существующего почтового ящика.
По умолчанию:
false
|
pin
|
body | string | необязательно |
Требуется, когда pin_enabled равно true: PIN из 6‑8 цифр, отправляемый как строка, чтобы сохранить ведущие нули.
|
pin_confirmation
|
body | string | необязательно |
Требуется, когда pin_enabled равно true. Должно точно соответствовать pin.
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
domain (например, outlook.com, hotmail.com), username (пользовательское имя псевдонима), lifetime (разрешённые значения: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Опустите срок жизни или оставьте его пустым, чтобы использовать Срок жизни письма по умолчанию, настроенный для вашего текущего ежемесячного/годового плана. Укажите разрешённый срок жизни, например 1h, чтобы переопределить значение по умолчанию. Неограниченный срок используется только когда он настроен как значение по умолчанию плана или явно запрошен и разрешён. Параметры тела mailbox_lifetime и email_lifetime также принимаются; первое непустое значение выигрывает в следующем порядке: lifetime, mailbox_lifetime, email_lifetime. Недопустимые или запрещённые значения возвращают HTTP 422 вместо того, чтобы молча выбирать значение по умолчанию.const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/outlook-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/outlook-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"id": 2306,
"pin_protected": false,
"email": "example+alias45@outlook.com",
"domain": "outlook.com",
"provider": "outlook_alias",
"expire_at": "2026-11-19T03:18:08+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:08+00:00",
"email_token": "encrypted-email-token"
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.id |
integer | Идентификатор почтового ящика. Сгенерированные идентификаторы, адреса и токены различаются для каждого ящика. |
data.pin_protected |
boolean | Указывает, защищён ли этот почтовый ящик PIN‑кодом. PIN или хеш PIN не возвращаются. |
data.email |
string | Сгенерирован полный адрес почтового ящика. |
data.domain |
string | Домен сгенерированного почтового ящика. |
data.provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
data.expire_at |
string|null | Эффективный срок истечения в виде метки времени ISO-8601, или null для неограниченного почтового ящика. |
data.expires_in_seconds |
number|null | Неотрицательное количество оставшихся секунд при расчёте; возможны дробные секунды. Null означает неограниченно, а не ноль. |
data.mailbox_state |
string | Текущее состояние почтового ящика: активно, приостановлено, истекло или неактивно. |
data.receiving_enabled |
boolean | Принимает ли этот почтовый ящик в настоящее время входящие сообщения. |
data.message_count |
integer | Известное общее количество сообщений; может отражать последнюю синхронизацию почтового ящика. |
data.unread_message_count |
integer | Известное количество непрочитанных сообщений; оно может отражать последнюю синхронизацию почтового ящика. |
data.last_message_received_at |
string|null | Последнее известное время получения сообщения в формате ISO-8601, или null, если недоступно. |
data.message_count_synced_at |
string|null | Время последней синхронизации количества сообщений в формате ISO-8601, или null до синхронизации. |
data.created_at |
string|null | Время создания почтового ящика в формате ISO-8601. |
data.email_token |
string | Непрозрачная зашифрованная ссылка на почтовый ящик. Она не заменяет аутентификацию Bearer, проверки прав собственности или авторизацию PIN. |
data.pin_grant |
object | Условно: при активном создании почтового ящика, защищённого PIN-кодом, возвращается это разрешение на чтение; обычное создание без защиты его не включает. |
data.pin_grant.mailbox_id |
integer | Идентификатор почтового ящика, к которому привязан условный грант на чтение. |
data.pin_grant.unlock_token |
string | Непрозрачный токен чтения для X-Mailbox-Unlock с теми же учётными данными владельца. Храните его в частном порядке и в памяти; предоставление прав чтения не даёт права на удаление. |
data.pin_grant.scope |
string | Область чтения для условного гранта создания. |
data.pin_grant.idle_timeout_seconds |
integer | Разрешённое время простоя для прав чтения, обычно 3600 секунд. |
data.pin_grant.absolute_timeout_seconds |
integer | Максимальное время жизни разрешения на чтение, обычно 86400 секунд. |
data.pin_grant.expires_at |
string | Текущий срок действия прав чтения в формате ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Абсолютный срок действия предоставления прав чтения в формате ISO-8601. Изменения в безопасности могут отозвать предоставление раньше. |
Сообщения и вложения
Получайте входящие почтовые ящики, читайте полные сообщения в формате HTML/текст и передавайте вложения в поток.
Список сообщений почтового ящика
Получить доступные сводки сообщений и метаданные почтового ящика. Стандартные сканирования входящих возвращают недавнюю партию до 25 сообщений; это не пагинированный эндпоинт полной истории. Используйте GET /messages/{messageId} для получения полных тел сообщений и вложений.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
email
|
query | string | обязательно |
Полный адрес электронной почты принадлежащего почтового ящика, из которого читать сообщения. URL‑закодируйте значение запроса; закодируйте знак плюс как %2B.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте read unlock_token. Сначала выполните POST pin и scope=read к PIN unlock URL. Сохраняйте обычную Bearer authentication. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages?email=demo123@example.com', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages?email=demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages?email=demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages?email=demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"mailbox": "demo123@example.com",
"email_token": "encrypted-email-token",
"messages": [
{
"is_seen": false,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"receivedAt": "2026-11-19 02:18:08",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"otp": null,
"otp_locked": false,
"verification_link": null,
"verification_link_locked": false
}
],
"mailbox_provider": "standard",
"mailbox_state": "active",
"expire_at": "2026-11-20T02:18:08+00:00",
"expires_in_seconds": 86399.75,
"receiving_enabled": true,
"mailbox_limit": {
"limit": 50,
"limit_label": "50",
"active_count": 1,
"paused_count": 0,
"paused_mailboxes": [],
"remaining": 49,
"remaining_label": "49",
"reached": false,
"blocked": false,
"provider": "standard"
},
"message_count": 1,
"unread_message_count": 1,
"last_message_received_at": "2026-11-19T02:18:08+00:00",
"message_count_synced_at": "2026-11-19T02:18:08+00:00"
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
mailbox |
string | Адрес почтового ящика, сообщения из которого были запрошены. |
email_token |
string | Непрозрачная зашифрованная ссылка на почтовый ящик; обычная аутентификация всё ещё требуется. |
mailbox_provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
messages |
array | Сводки сообщений. Пустой почтовый ящик возвращает пустой массив; получить отдельное сообщение для его тела и вложений. |
expire_at |
string|null | Эффективный срок истечения в виде метки времени ISO-8601, или null для неограниченного почтового ящика. |
expires_in_seconds |
number|null | Неотрицательное количество оставшихся секунд при расчёте; возможны дробные секунды. Null означает неограниченно, а не ноль. |
mailbox_state |
string | Текущее состояние почтового ящика: активно, приостановлено, истекло или неактивно. |
receiving_enabled |
boolean | Принимает ли этот почтовый ящик в настоящее время входящие сообщения. |
message_count |
integer | Известное общее количество сообщений; может отражать последнюю синхронизацию почтового ящика. |
unread_message_count |
integer | Известное количество непрочитанных сообщений; оно может отражать последнюю синхронизацию почтового ящика. |
last_message_received_at |
string|null | Последнее известное время получения сообщения в формате ISO-8601, или null, если недоступно. |
message_count_synced_at |
string|null | Время последней синхронизации количества сообщений в формате ISO-8601, или null до синхронизации. |
mailbox_limit.limit |
integer | Лимит активных почтовых ящиков для этого провайдера; -1 означает неограниченный. |
mailbox_limit.limit_label |
string | Отображаемая метка для ограничения почтового ящика. |
mailbox_limit.active_count |
integer | Количество активных почтовых ящиков для этого провайдера. |
mailbox_limit.paused_count |
integer | Количество приостановленных почтовых ящиков для этого провайдера. |
mailbox_limit.paused_mailboxes |
array<string> | Адреса приостановлены из‑за ограничения почтового ящика. |
mailbox_limit.remaining |
integer | Оставшиеся активные слоты почтовых ящиков; -1 означает неограниченно. Это не квота запросов API. |
mailbox_limit.remaining_label |
string | Отображаемая метка для оставшихся слотов почтового ящика. |
mailbox_limit.reached |
boolean | Было ли достигнуто ограничение активных почтовых ящиков. |
mailbox_limit.blocked |
boolean | Является ли активный лимит почтовых ящиков равным нулю. |
mailbox_limit.provider |
string|null | Провайдер, к которому применяется ограничение почтового ящика. |
messages[].id |
string | Неявный идентификатор сообщения, используемый конечными точками единственного сообщения, удаления и вложения. |
messages[].is_seen |
boolean | Отмечено ли сообщение как прочитанное. |
messages[].subject |
string | Тема сообщения. |
messages[].from |
string | Отображаемое имя или адрес отправителя. |
messages[].from_email |
string | Адрес электронной почты отправителя. |
messages[].receivedAt |
string | Время получения в часовом поясе приложения, отформатировано как YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | Обнаружен одноразовый код, когда он доступен и разрешён; иначе null. |
messages[].otp_locked |
boolean | Определяет, скрыт ли обнаруженный одноразовый код разрешениями функции. |
messages[].verification_link |
string|null | Обнаружен URL проверки, если доступен и разрешён; иначе null. |
messages[].verification_link_locked |
boolean | Является ли обнаруженная ссылка подтверждения скрытой из‑за разрешений функции. |
messages[].from_name |
string|null | Поле сводки Outlook: имя оригинального отправителя. Отсутствует в сводках Standard и Gmail. |
messages[].snippet |
string|null | Поле сводки Outlook: короткий предварительный просмотр сообщения. |
messages[].received_at |
string|null | Поле сводки Outlook: полученное время в формате ISO-8601, если известно. |
messages[].has_attachments |
boolean | Поле сводки Outlook: существует ли метаданные вложения. Доступность загрузки проверяется отдельно. |
Получить отдельное сообщение
Получить принадлежащее сообщение по его непрозрачному идентификатору сообщения. Возвращает форматы тела и метаданные вложений. Поля тела зависят от формата сообщения; Outlook добавляет специфические для провайдера поля, перечисленные ниже.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
messageId
|
path | string | обязательно |
Уникальный идентификатор сообщения, возвращаемый в списке сообщений.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте read unlock_token. Сначала выполните POST pin и scope=read к PIN unlock URL. Сохраняйте обычную Bearer authentication. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"data": {
"is_seen": true,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "demo123@example.com",
"mailbox_provider": "standard",
"receivedAt": "2026-11-19 02:18:08",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"html_content": "<p>Hello from the inbox.</p>",
"text_content": "<pre>Hello from the inbox.</pre>",
"content": "<p>Hello from the inbox.</p>",
"attachments": [
{
"name": "file.txt",
"extension": "txt",
"size": 91,
"url": "https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt"
}
]
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
data.id |
string | Непрозрачный идентификатор сообщения. |
data.is_seen |
boolean | Состояние прочтения сообщения. Чтение может пометить его как просмотренное; кэшированные данные могут отражать более раннее состояние. |
data.subject |
string | Тема сообщения. |
data.from |
string | Отображаемое имя или адрес отправителя. |
data.from_email |
string | Адрес электронной почты отправителя. |
data.to |
string | Адрес почтового ящика получателя. |
data.mailbox_provider |
string | Провайдер почтового ящика: standard, gmail_alias или outlook_alias. |
data.receivedAt |
string | Время получения в часовом поясе приложения, отформатировано как YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | Определяет, содержит ли сообщение HTML‑тело. |
data.html_content |
string | HTML‑тело, если присутствует. Стандартные сообщения без HTML могут опустить это поле. Считайте содержимое сообщения недоверенным. |
data.text_content |
string | Текстовое тело, если присутствует; Стандартные сообщения могут содержать экранированный текст в элементе pre или опустить это поле. |
data.content |
string | Предпочтительное тело для отображения, обычно HTML, если доступно. |
data.attachments |
array | Метаданные вложения, или пустой массив. Для загрузок требуется обычная аутентификация и соответствующая авторизация PIN. |
data.attachments[].name |
string | Имя файла для URL‑кодирования как единого сегмента пути при загрузке. |
data.attachments[].size |
integer | Размер вложения в байтах. |
data.attachments[].url |
string | URL загрузки API аутентифицированного пользователя добавлен к вложениям с именем файла. URL не гарантирует, что локальный файл доступен. |
data.attachments[].extension |
string | Стандартное/метаданные Gmail: расширение файла, если указано. |
data.attachments[].id |
string | Поле метаданных Outlook: идентификатор вложения поставщика. |
data.attachments[].content_type |
string | Поле метаданных Outlook: тип содержимого MIME. |
data.from_name |
string|null | Поле детали Outlook: имя оригинального отправителя. |
data.to_email |
string|null | Поле деталей Outlook: исходный адрес получателя. |
data.received_at |
string|null | Поле деталей Outlook: полученное время в формате ISO-8601. |
data.has_html |
boolean | Поле детали Outlook: существует ли HTML‑тело. |
Удалить сообщение
Удалить одно собственное сообщение.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
messageId
|
path | string | обязательно |
Уникальная строка идентификатора сообщения для постоянного удаления.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте одноразовый токен разблокировки delete unlock_token. Сначала выполните POST pin, scope=delete и action/target_id, возвращённые в ответе 423 на URL разблокировки PIN. Токен чтения не может удалять. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | необязательно |
Требуется для создания или удаления с защитой PIN: стабильный ключ длиной от 16 до 128 символов. Повторите идентичный запрос с тем же ключом, чтобы избежать дублирования работы.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| Поле | Тип | Описание |
|---|---|---|
status |
boolean | Успешно ли выполнена операция. |
message |
string | Результат удаления. Отсутствующий ресурс возвращает HTTP 404. |
Скачать вложение
Загрузить вложение из принадлежащего сообщения.
| Параметр | Местоположение | Тип | Статус | Описание |
|---|---|---|---|---|
messageId
|
path | string | обязательно |
Идентификатор сообщения, содержащего файл.
|
filename
|
path | string | обязательно |
Имя файла и расширение вложения для скачивания.
|
X-Mailbox-Unlock
|
header | string | необязательно |
Заголовок, только защищённые почтовые ящики: используйте read unlock_token. Сначала выполните POST pin и scope=read к PIN unlock URL. Сохраняйте обычную Bearer authentication. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const blob = await response.blob();
const downloadUrl = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = downloadUrl;
link.download = 'file.txt';
document.body.appendChild(link);
link.click();
link.remove();
window.URL.revokeObjectURL(downloadUrl);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', headers=headers, stream=True, timeout=30)
response.raise_for_status()
with open('file.txt', 'wb') as handle:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
handle.write(chunk)
<?php
$fileHandle = fopen('file.txt', 'w');
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_FILE => $fileHandle,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
if (curl_exec($ch) === false) {
fclose($fileHandle);
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
fclose($fileHandle);
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY' \
--output file.txt
| Поле | Тип | Описание |
|---|---|---|
Content-Disposition |
header | Успешный ответ загружает запрошенное имя файла. |
body |
binary | Байты файла при успехе, а не JSON. Ошибки возвращают JSON со статусом, не являющимся 2xx. |
Ограничения скорости и квоты
Отслеживайте бюджеты запросов в реальном времени, ограничения скорости и квоты аккаунта без расходования кредитов.
Ограничение скорости и квота
Проверьте текущий лимит запросов и статус квоты без использования API. Этот endpoint не учитывается в квоте и не списывает ежемесячные кредиты API (лимит защиты от злоупотреблений: 60 запросов/мин).
const response = await fetch('https://v1.tempmailg.com/api/rate-limit', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/rate-limit', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/rate-limit');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/rate-limit' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Иллюстративный ответ с использованием синтетических данных. Идентификаторы, адреса, токены, метки времени, ограничения плана и количества различаются. Примерные сроки жизни не переопределяют настройки вашего плана по умолчанию. Описания полей ответа указывают, какие могут быть null, и специфичные для провайдера поля.
Пример ответа
200 OK • JSON{
"status": "success",
"data": {
"limit": 60,
"remaining": 45,
"reset": 32,
"plan": "premium",
"monthly_limit": 50000,
"monthly_remaining": 48210,
"purchased_credits": 5000,
"quota": {
"enabled": true,
"user_api_status": true,
"plan_name": "Premium Plan",
"period": "2026-10",
"base_limit": 50000,
"extra_requests": 0,
"monthly_limit": 50000,
"monthly_remaining": 48210,
"used": 1790,
"purchased_credits": 5000,
"bonus_credits": 1000,
"direct_purchased_credits": 4000,
"remaining": 53210,
"unlimited": false,
"usage_percent": 3,
"reset_at": "2026-11-01T00:00:00+00:00"
}
}
}
| Поле | Тип | Описание |
|---|---|---|
data.limit |
integer|string | Лимит запросов в минуту аккаунта. Строка unlimited обозначает неограниченный минутный бюджет; это независимо от месячной квоты. |
data.remaining |
integer|string | Оставшиеся слоты минутного бюджета аккаунта, или строка unlimited. Положительное значение не означает, что остаются кредиты API. |
data.reset |
integer | Секунды для минутного окна аккаунта, а не для сброса месячной квоты. Отключённые или неограниченные минутные бюджеты могут сохранять номинальное значение 60 секунд; это не гарантирует доступ после ожидания. |
data.plan |
string | Текущий тег плана. Читаемое название плана предоставляется отдельно в data.quota.plan_name. |
data.quota.enabled |
boolean | Включён ли глобальный и плановый/кредитный доступ к API. Это не указывает оставшуюся ёмкость и не заменяет переключатель API пользователя. |
data.quota.user_api_status |
boolean | Включил ли пользователь переключатель User API. Операции требуют этого переключателя, а также включённого доступа и доступной ёмкости. |
data.quota.plan_name |
string | Читаемое название текущего плана. |
data.quota.period |
string | Период использования в формате календарного месяца YYYY-MM, с учётом часового пояса приложения; не обязательно совпадает с периодом выставления счета по подписке. |
data.quota.base_limit |
integer | Базовое месячное ограничение плана. Значение -1 означает неограниченно. |
data.quota.extra_requests |
integer | Дополнительный ежемесячный лимит предоставлен для текущего периода использования; отдельно от приобретённых кредитов. |
data.quota.monthly_limit |
integer | Базовое пособие плюс дополнительные запросы текущего периода. Значение -1 означает неограниченный. Приобретённые кредиты не включены. |
data.quota.monthly_remaining |
integer|null | Оставшееся конечное месячное пособие, или null, когда месячная квота не ограничена. Null не должен интерпретироваться как ноль. |
data.quota.used |
integer | Успешные, учитываемые операции API в текущем периоде использования, включая операции с использованием кредитов. Проверки статуса не увеличивают это значение. |
data.quota.purchased_credits |
integer | Текущий баланс кредитов, включая бонусные кредиты активного плана. Бонусные кредиты не должны добавляться к этому балансу второй раз. |
data.quota.bonus_credits |
integer | Активная часть бонуса плана в балансе кредитов; разбивка purchased_credits, а не дополнительная емкость. |
data.quota.direct_purchased_credits |
integer | Баланс кредитов без учёта активной части бонуса плана. Это значение плюс bonus_credits равно purchased_credits. |
data.quota.remaining |
integer|null | Оставшийся месячный лимит плюс текущий баланс кредита, без двойного учёта бонусов. Null означает неограниченную месячную квоту. Индивидуальные разрешения функций и другие ограничения запросов по‑прежнему применяются. |
data.quota.unlimited |
boolean | Указывает, является ли месячная квота неограниченной. Это не делает неограниченным бюджет минут аккаунта или другие ограничения функций. |
data.quota.usage_percent |
integer | Округленный процент от 0 до 100, совместимый с панелью управления: использовано, делённое на использовано плюс оставшееся, умноженное на 100. Включает доступную кредитную емкость, поэтому пополнение может снизить процент. Он равен 0 для неограниченной квоты или пула нулевого размера; это не процент ограничения скорости в минуту и не решение о доступе. |
data.quota.reset_at |
string | Отметка времени в формате ISO-8601 с указанием часового пояса для следующего сброса квоты за календарный месяц. Это не дата истечения подписки, и ежемесячный сброс не пополняет приобретённые кредиты. |
status |
string | Буквальный успех для этой конечной точки статуса. Другие успешные конечные точки почтовых ящиков используют логическое true. |
data.monthly_limit |
integer | Совместимый псевдоним соответствующего поля data.quota; не добавляйте его повторно при расчёте балансов. |
data.monthly_remaining |
integer|null | Совместимый псевдоним соответствующего поля data.quota; не добавляйте его повторно при расчёте балансов. |
data.purchased_credits |
integer | Совместимый псевдоним соответствующего поля data.quota; не добавляйте его повторно при расчёте балансов. |
Веб-хуки почтового ящика (реальное время push)
Вместо многократного опроса REST-API (GET /messages) для проверки входящей почты, настройте вебхуки для отправки новых сообщений на ваш сервер или автоматизированные рабочие процессы в реальном времени.
Поддерживаемые события вебхуков
Каждый вебхук может подписываться на один или несколько типов событий. Ваш эндпоинт получает уведомление об событии, когда одно из этих триггеров срабатывает.
Отправляется в реальном времени каждый раз, когда новое сообщение поступает в выбранный почтовый ящик.
Отправляется, когда временный почтовый ящик истекает и обработка вебхука приостанавливается.
Отправляется, когда истёкший почтовый ящик снова становится активным согласно правилам плана.
Отправлено непосредственно перед удалением вебхука и его почтового ящика.
Запросы заголовков & проверка HMAC-подписи
Каждая доставка вебхука содержит специальные заголовки безопасности. Используйте заголовок X-TempMailg-Signature для проверки того, что входящие запросы были отправлены TempMailg и не были изменены.
| Название заголовка | Пример значения | Описание |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Стандартный идентификатор для работника доставки вебхуков. |
X-TempMailg-Event |
email.received | Тип события, которое вызвало эту доставку. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | Уникальный UUID, назначенный этой попытке доставки. |
X-TempMailg-Timestamp |
1725192000 | Отметка времени Unix epoch, указывающая, когда был инициирован запрос. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | Подпись HMAC-SHA256, вычисленная из {timestamp}.{raw_body} с использованием вашего секрета. |
X-TempMailg-Test |
false | Истина, когда отправлено функцией "Send Test Ping" в вашей панели управления. |
Подпись вычисляется с использованием HMAC с SHA256 для строки:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
Пример события оповещения (email.received)
Отправляется как application/json в теле HTTP-запроса POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:18:08+00:00",
"test": false,
"mailbox": {
"id": 1024,
"email": "developer@v1.tempmailg.com"
},
"data": {
"message_id": "7a8b9c0d1e2f",
"subject": "Your Verification Code: 948201",
"from": "auth@service.com",
"to": "developer@v1.tempmailg.com",
"date": "2026-11-19T02:18:08+00:00",
"attachments_count": 0,
"text_preview": "Hello, your one-time verification code is 948201. It will expire in 10 minutes.",
"email_url": "https://tempmailg.com/mailbox/1024?message=7a8b9c0d1e2f",
"inbox_url": "https://tempmailg.com/mailbox/1024"
}
}
Примеры реализации получателя
Выберите язык, чтобы увидеть, как безопасно получать вебхуки и проверять подписи HMAC.
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = 'your_webhook_signing_secret';
// Capture raw body buffer for HMAC-SHA256 signature verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString('utf8');
}
}));
app.post('/webhook', (req, res) => {
const timestamp = req.headers['x-tempmailg-timestamp'];
const signatureHeader = req.headers['x-tempmailg-signature'] || '';
// Calculate HMAC-SHA256 signature
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${timestamp}.${req.rawBody}`)
.digest('hex');
// Verify signature
if (signatureHeader !== expectedSignature) {
return res.status(401).json({ error: 'Invalid webhook signature' });
}
const { event, mailbox, data } = req.body;
console.log(`[Event: ${event}] Mailbox: ${mailbox.email}`);
if (event === 'email.received') {
console.log(`From: ${data.from}`);
console.log(`Subject: ${data.subject}`);
console.log(`Preview: ${data.text_preview}`);
}
// Acknowledge receipt with HTTP 200
res.status(200).json({ received: true });
});
app.listen(3000, () => console.log('Webhook receiver running on port 3000'));
from flask import Flask, request, jsonify
import hmac
import hashlib
app = Flask(__name__)
WEBHOOK_SECRET = b"your_webhook_signing_secret"
@app.route("/webhook", methods=["POST"])
def handle_webhook():
timestamp = request.headers.get("X-TempMailg-Timestamp", "")
signature_header = request.headers.get("X-TempMailg-Signature", "")
# Calculate expected HMAC-SHA256 signature
raw_body = request.get_data()
signed_payload = f"{timestamp}.".encode("utf-8") + raw_body
expected_signature = "sha256=" + hmac.new(
WEBHOOK_SECRET, signed_payload, hashlib.sha256
).hexdigest()
# Verify signature securely
if not hmac.compare_digest(signature_header, expected_signature):
return jsonify({"error": "Invalid signature"}), 401
payload = request.get_json()
event = payload.get("event")
mailbox = payload.get("mailbox", {}).get("email")
data = payload.get("data", {})
print(f"[{event}] Mailbox: {mailbox}")
if event == "email.received":
print(f"From: {data.get('from')}")
print(f"Subject: {data.get('subject')}")
print(f"Preview: {data.get('text_preview')}")
# Return 200 OK to acknowledge receipt
return jsonify({"received": True}), 200
if __name__ == "__main__":
app.run(port=5000)
<?php
$secret = 'your_webhook_signing_secret';
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TEMPMAILG_TIMESTAMP'] ?? '';
$receivedSignature = $_SERVER['HTTP_X_TEMPMAILG_SIGNATURE'] ?? '';
// Calculate HMAC-SHA256 signature
$expectedSignature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
// Verify signature
if (!hash_equals($expectedSignature, $receivedSignature)) {
http_response_code(401);
echo json_encode(['error' => 'Invalid signature']);
exit;
}
$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? '';
$mailbox = $payload['mailbox']['email'] ?? '';
$data = $payload['data'] ?? [];
if ($event === 'email.received') {
$sender = $data['from'] ?? '';
$subject = $data['subject'] ?? '';
$preview = $data['text_preview'] ?? '';
// Process new incoming email...
}
// Acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);
Поддерживаемые платформы и интеграции автоматизации
TempMailg Webhooks работают сразу из коробки со стандартными HTTPS‑конечными точками и ведущими платформами без кода/автоматизации:
Общие ошибки и устранение неполадок
Это наиболее распространенные коды ответов, которые вы можете увидеть при интеграции API пользователя.
Недействительный, отсутствующий или отозванный токен Bearer.
Владение, разрешения функций, доступ к домену или размер вложения помешали выполнению операции. Проверьте код ответа и сообщение.
Ресурс не найден на разрешенном хосте или не принадлежит пользователю.
Ключ операции был повторно использован с другими деталями, другая операция ожидает выполнения, или безопасность почтового ящика изменена. Проверьте код перед повторной попыткой.
Почтовый ящик истек или неактивен.
Недопустимые параметры, запрещённый срок жизни, недоступная ёмкость псевдонима, неверная настройка PIN-кода или отсутствующий/недействительный Idempotency-Key помешали выполнению операции.
Защищённый почтовый ящик требует действительный токен X-Mailbox-Unlock с областью. Используйте параметры action и target_id из ответа для удаления. Требования блокировки или восстановления должны быть выполнены перед повторной попыткой.
Лимит запросов, отключённый план, исчерпанная квота или время ожидания предотвратили операцию. Проверьте причину и заголовки доступного бюджета. Retry-After является необязательным.
Сервер не смог завершить операцию. При защищённом создании или удалении сохраняйте тот же запрос и Idempotency-Key при повторной попытке.
Хранилище защиты или координацию не удалось проверить. Повторите попытку после указанной задержки. Этот ответ не является неудачной оплатой.
Быстрый чек-лист
- 401 Unauthorized - Токен Bearer отсутствует, неверен, отозван или скопирован неправильно.
- 403 Forbidden - Текущий план не имеет права доступа к API пользователя в настоящее время.
- 404 Not Found - Ресурс не найден или указан неверный параметр
- 410 Gone / Expired - Почтовый ящик истёк или больше не активен.
- 429 Rate Limited - Проверьте причину ответа и заголовки бюджета. Retry-After применяется только к ограниченным по времени лимитам; исчерпанные кредиты или отключённый доступ могут потребовать изменения аккаунта.
Рекомендуемый следующий шаг
Если вы авторизованы, сначала откройте API Management и подтвердите статус ключа, квоты, плана доступа и точный базовый URL пользовательского API перед отладкой вашего внешнего приложения.