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 for production; use the sandbox sender only with simulator recipients while testing.

Free can send real email from one verified domain. Outbound REST attachments require Pro or Custom.

For a buyer-level overview, see the transactional email API guide.

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",
    "sendAt": "2026-07-10T15:00:00.000Z",
    "tracking": { "opens": false, "clicks": false },
    "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.
`tracking`	{ opens?: boolean, clicks?: boolean }	Optional per-send override. Omit to use the sending domain defaults; set either field false to leave that pixel or redirect out.
`sendAt`	ISO timestamp	Optional scheduled delivery time, up to 30 days ahead. Omit for immediate delivery.
`attachments`	array	[{ filename, content (base64), contentType?, contentId? }], about 5MB decoded total, 10 max. Pro or Custom only for outbound sends.

Idempotency

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

Scheduled sending

Add sendAt to queue a transactional email up to 30 days ahead. The minute scheduler claims due sends and runs the same domain, suppression, quota, tracking, and daily-limit checks used by immediate sends.

{
  "ok": true,
  "id": "sch_...",
  "status": "scheduled",
  "scheduledAt": "2026-07-10T15:00:00.000Z",
  "provider": "noticeapi_scheduled",
  "messageId": null
}

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).