REST API reference

NoticeAPI exposes a project-aware JSON REST API for transactional email, consent-based marketing, domains, templates, receiving, webhooks, access management, and invited private-beta SMS. This page summarizes the surface; the canonical, machine-readable contract is OpenAPI 3.1.

Base URL and auth

GET/api/v1/...

Production endpoints live under https://www.noticeapi.com/api/v1. Except for the liveness probe, authenticate with Authorization: Bearer ntc_.... API keys are shown once after creation; learn the scopes and flow in the account API keys guide.

curl https://www.noticeapi.com/api/v1/emails/EMAIL_ID \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

Project context

Project-bound keys require no project header. For email sends, a workspace key can also omit the header: NoticeAPI resolves the project from the verified domain in from. This lets one key send from domains across several projects without another environment variable. Use X-NoticeAPI-Project-ID for project-local management endpoints, sandbox sends, or when you want an explicit guard. A header that conflicts with the sender domain returns project_not_allowed; a request that cannot be resolved safely returnsproject_required.

Scoped keys

Full-access keys carry every scope. For apps, CI jobs, and authorized agents, create a key with only the scopes that workflow needs. Out-of-scope calls return 403 and the stable insufficient_scope code.

{
  "error": "This API key does not have the broadcasts:write scope. Create a key with the scopes this integration needs.",
  "code": "insufficient_scope"
}

Idempotency and retries

The single-email send endpoint accepts an Idempotency-Key header up to 256 characters. Repeating the same key returns the original result instead of sending twice, which is the safest retry pattern for agents, queues, and webhooks. Reusing a key with a different payload returns 409 idempotency_mismatch. Batch email sends do not accept idempotency keys; SMS uses its own required idempotency header.

curl -X POST https://www.noticeapi.com/api/v1/email/send \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: receipt-8412" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": "[email protected]",
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase.</p>"
  }'

Endpoint inventory

Testing without sending real mail

Use [email protected] as the sender and recipients at simulator.noticeapi.com to exercise delivered, bounced, complained, and suppressed outcomes without using ACS or sending real mail.

Errors and limits

API errors return JSON with error and a stable code. Agents should branch on the code, respect Retry-After on 429, and stop on policy boundaries such as insufficient_scope, recipient_suppressed, and quota_exceeded. See Errors and limits.