Send an email

Queue a message from a verified domain.

POST/api/v1/emails

One sender and one recipient per request. The sender must belong to a verified domain on your account. Returns 202 Accepted with a job ID.

Request

POST /api/v1/emails

curl 'API_BASE_URL/api/v1/emails' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Idempotency-Key: welcome-user-123' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "emails",
      "attributes": {
        "from": "My App <[email protected]>",
        "to": "[email protected]",
        "subject": "Welcome aboard",
        "text": "Your account is ready.",
        "html": "<h1>Welcome aboard</h1><p>Your account is ready.</p>"
      }
    }
  }'

Replace the API key, verified sender, and recipient. Use a unique idempotency key for each email. API_BASE_URL, when shown, means this Sendy instance’s origin.

Required headers

Authorization: Bearer API_KEY. See Authentication.
Content-Type: application/vnd.api+json. Use a JSON:API resource document with data.type and data.attributes.
Idempotency-Key: A unique key of 1–128 bytes identifying this email. Reuse it for an unchanged request after a timeout.

JSON body

Provide text, html, or both. At least one must contain more than whitespace. Unsupported fields are rejected. Limits are measured in bytes.

from: RequiredOne sender on your verified domain, such as [email protected] or My App <[email protected]>. ASCII only; address up to 254 bytes, display name up to 128 bytes, and full value up to 512 bytes. Control characters are rejected.
to: RequiredOne valid recipient email address, without a display name. ASCII only; up to 254 bytes.
subject: RequiredA nonblank subject of 1 to 255 bytes, without carriage returns or line breaks.
text: If html is omitted or blankPlain-text content, up to 60,000 bytes.
html: If text is omitted or blankHTML content, up to 60,000 bytes.

Display names go in from: My App <[email protected]>. Quote names containing commas, such as "App, Support" <[email protected]>, and escape those quotes in JSON.

Response 202

Queued email · application/vnd.api+json

{
  "jsonapi": {
    "version": "1.1"
  },
  "data": {
    "type": "emails",
    "id": "123",
    "attributes": {
      "from": "My App <[email protected]>",
      "status": "queued",
      "attempts": 0,
      "message_id": null,
      "last_error": null,
      "delivery_status": null,
      "delivery_at": null,
      "delivery_detail": null
    }
  }
}

The message is stored for background delivery. This response does not confirm provider acceptance or inbox delivery. Use the id to get its status.