SMTP и HTTP API

Отправлять письма через поток можно двумя способами: по SMTP из любого приложения или почтовой библиотеки либо через HTTP API. Оба способа используют одни и те же ключи API, квоты, список подавления и события. Прежде чем начать, подтвердите домен отправки и создайте ключ API.

#Ключи API

1. Откройте поток и перейдите на вкладку Ключ API.
2. Нажмите Создать ключ, введите Название, например production, и подтвердите.
3. Скопируйте показанный ключ и нажмите Я сохранил. Ключ показывается только этот один раз. Затем в списке отображается только его Префикс, например ytm_aB3dE6gH….

Каждый ключ начинается с ytm_. У потока может быть до 20 активных ключей. В списке указано, когда каждый ключ использовался в последний раз. Чтобы вывести ключ из использования, нажмите Отозвать: программы, которые его используют, сразу перестанут работать. Ключ действует только для потока, которому он принадлежит.

#SMTP

На вкладке Обзор потока показаны настройки SMTP:

Используйте хост, указанный в консоли. Некоторые потоки отправляют почту через другую группу серверов с собственным именем хоста.

Как работает отправка по SMTP:

• В заголовке From должен быть адрес на домене, подтверждённом для потока.
• Каждый получатель (To, Cc и Bcc) получает собственную копию с собственным идентификатором письма и засчитывается как одно письмо.
• Чтобы задать категорию, добавьте заголовок, например X-Yeap-Category: password-reset. Он удаляется перед доставкой. Допустимые символы: буквы, цифры, ., _ и -, не более 64 символов.
• Размер письма — до 25 MB, до 1,000 получателей на одну SMTP-транзакцию.
• Каждое письмо получает заголовок X-TM-ID (идентификатор письма, который отображается в журнале отправки и в событиях) и заголовок Feedback-ID для петель обратной связи почтовых провайдеров.
• В маркетинговых потоках любой заданный вами заголовок List-Unsubscribe заменяется заголовками отписки в один клик от Yeap Cloud. SMTP не изменяет тело письма, поэтому добавьте почтовый адрес и ссылку для отписки в содержимое самостоятельно. См. Подавление и отписка.
• Отслеживание открытий и кликов доступно только через HTTP API.

Пример со стандартной библиотекой Python:

import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Example <noreply@example.com>"
msg["To"] = "user@example.org"
msg["Subject"] = "Reset your password"
msg["X-Yeap-Category"] = "password-reset"
msg.set_content("Click the link to reset your password: https://example.com/reset/abc")

with smtplib.SMTP("smtp.tm.yeapcloud.net", 587) as s:
    s.starttls()
    s.login("apikey", "ytm_your_api_key")
    s.send_message(msg)

#Коды ответа SMTP

Когда сервер отклоняет письмо, код ответа указывает причину. Коды 4xx временные: повторите попытку позже. Коды 5xx постоянные: устраните причину, прежде чем отправлять снова.

#HTTP API

При ошибке возвращаются код состояния HTTP и тело следующего вида:

{"error": {"code": "invalid_request", "message": "subject is required (single line)"}}

#Отправка письма: POST /v1/send

Один вызов может содержать не более 50 получателей в сумме по to, cc и bcc. Каждый получатель получает отдельную копию с собственным идентификатором письма. Чтобы отправить разное содержимое множеству людей, используйте пакетный эндпоинт.

Пример:

curl -X POST https://api.tm.yeapcloud.net/v1/send \
  -H "Authorization: Bearer ytm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Example <noreply@example.com>",
    "to": ["alice@example.org"],
    "subject": "Your order {{order_id}} has shipped",
    "html": "<p>Hi {{name}}, your order is on its way.</p>",
    "text": "Hi {{name}}, your order is on its way.",
    "category": "shipping",
    "tags": ["order"],
    "variables": {"name": "Alice", "order_id": "A-1024"}
  }'

Ответ:

{
  "message_ids": ["01JAQ3Z9V8K4M2N6P7R5S1T0XW"],
  "rejected": []
}

В message_ids перечислены принятые копии. В rejected перечислены получатели, которым письмо не было отправлено, каждый с полями rcpt и reason. Вызов может завершиться успешно, даже если часть или все получатели отклонены, поэтому всегда проверяйте rejected:

Пример на Python с requests:

import requests

resp = requests.post(
    "https://api.tm.yeapcloud.net/v1/send",
    headers={"Authorization": "Bearer ytm_your_api_key"},
    json={
        "from": "Example <noreply@example.com>",
        "to": "alice@example.org",
        "subject": "Welcome",
        "html": "<p>Welcome aboard!</p>",
        "text": "Welcome aboard!",
        "category": "welcome",
    },
    timeout=30,
)
resp.raise_for_status()
result = resp.json()
print(result["message_ids"], result["rejected"])

#Пакетная отправка: POST /v1/batch

Отправляйте до 500 писем одним запросом. У каждого элемента те же поля, что и у /v1/send.

{
  "messages": [
    {"from": "noreply@example.com", "to": "a@example.org", "subject": "Hi A", "text": "Hello A"},
    {"from": "noreply@example.com", "to": "b@example.org", "subject": "Hi B", "text": "Hello B"}
  ]
}

Ответ содержит по одному результату на каждое письмо в том же порядке:

{
  "results": [
    {"index": 0, "message_ids": ["01JAQ..."], "rejected": []},
    {"index": 1, "error": {"code": "invalid_request", "message": "subject is required (single line)"}, "rejected": []}
  ]
}

#Поиск писем: GET /v1/messages

Ответ имеет вид {"data": [...], "next_before": "..."}. На последней странице next_before равен null. Письма хранятся 30 дней.

GET /v1/messages/{id} возвращает одно письмо и его события:

{
  "id": "01JAQ3Z9V8K4M2N6P7R5S1T0XW",
  "stream_id": 12,
  "source": "api",
  "to": "alice@example.org",
  "from": "Example <noreply@example.com>",
  "subject": "Welcome",
  "category": "welcome",
  "tags": [],
  "status": "delivered",
  "smtp_code": 250,
  "smtp_response": "250 2.0.0 OK",
  "opened_at": null,
  "clicked_at": null,
  "unsubscribed_at": null,
  "created_at": "2026-10-20 10:15:02",
  "updated_at": "2026-10-20 10:15:04",
  "events": [
    {"type": "delivered", "at": "2026-10-20 10:15:04", "rcpt": "alice@example.org", "smtp_code": 250, "mx": "mx.example.org"}
  ]
}

#Список подавления: /v1/suppressions

Эти эндпоинты управляют списком подавления потока, которому принадлежит ключ API.

Адреса, добавленные через API, получают причину manual. Записи подавления уровня аккаунта и глобальные записи изменить через API нельзя. См. Подавление и отписка.

#См. также

• События и вебхуки
• Лимиты, песочница и соответствие требованиям
• Домены отправки и DNS