Sending

Tags and headers

Label emails with tags to find them later, and add custom headers to the message, with the naming rules and limits that apply.

Tags and headers are two optional fields on POST /emails. Tags are metadata that stay in Sooner. Headers become part of the email message itself.

Tags

A tag is a name and value pair that you attach to an email so you can identify it later, for example the kind of email or the order it belongs to.

JSON

{
  "tags": [
    { "name": "category", "value": "password_reset" },
    { "name": "user_id", "value": "u_1042" }
  ]
}

Rule	Detail
Count	Up to 10 tags per email.
Name	1 to 256 characters: letters, numbers, underscore (`_`) and hyphen (`-`) only.
Value	1 to 256 characters: letters, numbers, underscore (`_`) and hyphen (`-`) only.

Spaces, dots, at-signs and other punctuation are rejected with validation_error. Use an identifier such as u_1042 rather than an email address.

Tags do not change how the email is sent and are not visible to the recipient. They are stored with the email and returned as tags by GET /emails/{id} and GET /emails, so you can match an email to your own records.

Custom headers

headers adds your own headers to the message. It is an object whose keys and values are both strings.

JSON

{
  "headers": {
    "X-Entity-Ref-ID": "order-1042",
    "X-Priority": "1"
  }
}

Shell

curl -X POST https://api.sooner.dev/emails \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <orders@mail.yourcompany.com>",
    "to": ["ada@example.com"],
    "subject": "Your order is confirmed",
    "html": "<p>Thanks for your order.</p>",
    "headers": { "X-Entity-Ref-ID": "order-1042" },
    "tags": [{ "name": "category", "value": "order_confirmation" }]
  }'

Headers are included in the message, so the recipient's mail client and any intermediate servers can see them. Do not put secrets in them. Use the dedicated fields (from, to, subject, reply_to, cc, bcc) rather than setting those through headers.

Headers Sooner sets for you

Message-ID is generated from the email ID and your sending domain.
List-Unsubscribe and List-Unsubscribe-Post are added, with one-click unsubscribe, to every broadcast, and to an email that sets topic_id when the recipient is a known contact. If you pass your own List-Unsubscribe on one of those emails, Sooner's value replaces it. See Unsubscribes.

For other bulk or marketing mail that is not a broadcast and does not use a topic, set your own List-Unsubscribe and List-Unsubscribe-Post headers so mailbox providers show an unsubscribe control.

JSON

{
  "headers": {
    "List-Unsubscribe": "<https://yourcompany.com/unsubscribe?u=1042>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}