SMTP and HTTP API

You can send through a stream in two ways: over SMTP from any application or mail library, or with the HTTP API. Both use the same API keys, quotas, suppression list and events. Before you start, verify a sending domain and create an API key.

#API keys

1. Open the stream and go to the API key tab.
2. Click Create key, enter a Name such as production, and confirm.
3. Copy the key that's shown and click I've saved it. The key is shown only this once. Afterwards the list shows only its Prefix, such as ytm_aB3dE6gH….

Each key starts with ytm_. A stream can have up to 20 active keys. The list shows when each key was last used. To retire a key, click Revoke: programs using it stop working immediately. A key works only for the stream it belongs to.

#SMTP

The Overview tab of the stream shows the SMTP settings:

Use the host shown in the console. Some streams send through a different server group with its own host name.

How SMTP sending works:

• The From header must use an address at a domain verified for the stream.
• Each recipient (To, Cc and Bcc) gets its own copy and its own message ID, and counts as one email.
• To set a category, add a header such as X-Yeap-Category: password-reset. It's removed before delivery. Allowed characters are letters, digits, ., _ and -, up to 64 characters.
• A message can be up to 25 MB, with up to 1,000 recipients per SMTP transaction.
• Every message gets an X-TM-ID header (the message ID that appears in the sending log and in events) and a Feedback-ID header for mailbox providers' feedback loops.
• On marketing streams, any List-Unsubscribe header you set is replaced with Yeap Cloud's one-click unsubscribe headers. SMTP doesn't change the message body, so add your postal address and an unsubscribe link to the content yourself. See Suppressions and unsubscribe.
• Open and click tracking are only available through the HTTP API.

Example with Python's standard library:

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 response codes

When the server refuses a message, the reply code tells you why. 4xx codes are temporary: retry later. 5xx codes are permanent: fix the cause before sending again.

#HTTP API

Errors return an HTTP status code and a body like this:

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

#Send a message: POST /v1/send

A single call can have up to 50 recipients in total across to, cc and bcc. Each recipient gets a separate copy with its own message ID. To send different content to many people, use the batch endpoint.

Example:

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"}
  }'

Response:

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

message_ids lists the accepted copies. rejected lists recipients that weren't sent, each with a rcpt and a reason. A call can succeed with some or even all recipients rejected, so always check rejected:

Python example with 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"])

#Send in bulk: POST /v1/batch

Send up to 500 messages in one request. Each item has the same fields as /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"}
  ]
}

The response has one result per message, in the same order:

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

#Look up messages: GET /v1/messages

The response is {"data": [...], "next_before": "..."}. next_before is null on the last page. Messages are kept for 30 days.

GET /v1/messages/{id} returns one message and its events:

{
  "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"}
  ]
}

#Suppressions: /v1/suppressions

These endpoints manage the suppression list of the API key's stream.

Addresses added through the API have the reason manual. Account-wide and global suppressions can't be changed with the API. See Suppressions and unsubscribe.

#Related

• Events and webhooks
• Limits, sandbox and compliance
• Sending domains and DNS