Send email

POST/api/v1/email/send

Sends one transactional email to up to 10 recipients across to/cc/bcc. Every address field accepts "Name <addr@domain>". The from-domain must be verified (or the sandbox sender while testing).

curl -X POST https://www.noticeapi.com/api/v1/email/send \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: welcome-8412" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <[email protected]>",
    "to": ["[email protected]"],
    "replyTo": "[email protected]",
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase!</p>",
    "headers": { "X-Entity-Ref-ID": "order-8412" },
    "attachments": [
      { "filename": "receipt.pdf", "content": "BASE64...", "contentType": "application/pdf" }
    ]
  }'

Body fields

Field	Type	Description
`from`required	string	Bare address or Name <addr>. Domain must be verified for production.
`to`required	string \| string[]	Up to 10 recipients per message total.
`cc / bcc`	string \| string[]	Optional additional recipients.
`replyTo`	string \| string[]	Where replies go.
`subject`required	string	Up to 998 characters.
`text / html`required	string	At least one. text ≤ 500KB, html ≤ 1MB.
`headers`	object	Custom headers (e.g. List-Unsubscribe, X-Entity-Ref-ID). Identity headers are blocked.
`attachments`	array	[{ filename, content (base64), contentType?, contentId? }] — ~5MB decoded total, 10 max. Paid plans only in production.

Idempotency

Pass an Idempotency-Key header (≤256 chars). Retries with the same key return the original result with idempotentReplay: true instead of sending twice. Keys persist with the email log.

Response

{
  "ok": true,
  "id": "5f0c1a...",           // use with GET /api/v1/emails/:id
  "provider": "noticeapi_email_api",
  "messageId": "0f83..."
}

Failure modes are listed in Errors & limits — the important ones: recipient_suppressed (409), quota_exceeded (403), daily_limit_reached (429), domain_not_ready (409).