API reference

Send email

POST/api/v2/emails

Queues one email and returns its ID. Works with sending and full keys.

Body

Send a JSON object with Content-Type: application/json.

FieldTypeDescription
fromstring, requiredSender, as hello@acme.com or Acme <hello@acme.com>. In live mode it must be on a verified domain or a verified sender address.
tostring or array, requiredRecipient or recipients. Up to 50 recipients across to, cc and bcc.
subjectstring, requiredUp to 998 characters.
htmlstringHTML body.
textstringPlain text body. Send html, text or both. When you send only HTML, a text part is generated at delivery.
ccstring or arrayCarbon copy recipients.
bccstring or arrayBlind carbon copy recipients.
reply_tostring or arrayReply-To addresses. replyTo is also accepted.
headersobjectCustom headers, for example {"X-Entity-Ref-ID": "1042"}. Header names may contain letters, numbers and dashes. Headers that have their own field (From, To, Subject…) cannot be set here.
tagsarrayUp to you: [{"name": "category", "value": "receipt"}]. Names and values may contain ASCII letters, numbers, _ and -, up to 256 characters.
attachmentsarrayFiles, see below.

Attachments

FieldTypeDescription
filenamestring, requiredFile name shown to the recipient.
contentstring, requiredFile content, base64 encoded.
content_typestringMedia type, for example application/pdf.
content_idstringSet it to embed the file inline and reference it in HTML as cid:<content_id>. Letters, numbers and . _ @ + -.

Attachments may total up to 40 MB per email (decoded size). Attachments by URL or path are not supported yet.

Headers

HeaderDescription
AuthorizationBearer <your API key>. Required.
Idempotency-KeyOptional, up to 256 characters. Retrying with the same key and body returns the first email instead of sending again, for 24 hours. See Idempotency.

Example

curl -X POST https://robustemail.com/api/v2/emails \
  -H "Authorization: Bearer $ROBUSTEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2041" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["jane@example.com"],
    "reply_to": "support@acme.com",
    "subject": "Your invoice #2041",
    "html": "<p>Hi Jane, your invoice is attached.</p>",
    "tags": [{ "name": "category", "value": "invoice" }],
    "attachments": [
      {
        "filename": "invoice-2041.pdf",
        "content": "JVBERi0xLjQKJ...",
        "content_type": "application/pdf"
      }
    ]
  }'

Response

{ "id": "6adc79043cbea" }

The email is queued and delivered in the background. Follow it in Developers › Emails or with Retrieve email.

Recipients on your account’s suppression list (people who bounced, complained or were blocked) are removed before sending. If every recipient is suppressed, the email ends with the suppressed status.

Errors

StatusnameWhen
422validation_errorA field is missing or invalid. The message says which.
403invalid_from_addressThe from domain is not verified (live mode).
403restricted_api_keyThe key is limited to another domain, or the account has no active subscription.
409invalid_idempotent_requestThe Idempotency-Key was used before with a different body.

See Errors for the full list.