Send Email API Guide & POST /api/v1/email/send Reference

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 after a card is added through secure Stripe setup. Outbound REST attachments require a paid plan.

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 <billing@acme.com>",
    "to": ["user@example.com"],
    "replyTo": "support@acme.com",
    "subject": "Your receipt",
    "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. Paid plans 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 delivery record.

Scheduled sending

Add sendAt to queue a transactional email up to 30 days ahead. Use a real timestamp after now; past timestamps are rejected. 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": "<future ISO 8601 timestamp>",
  "provider": "noticeapi_scheduled",
  "messageId": null
}

Response

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

A production send returns 202 after NoticeAPI records its delivery record and dispatch job. Fetch the id to read queued, sending, accepted, failed, or uncertain. Simulator sends and idempotent replays return 200.

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