REST API reference
NoticeAPI exposes a project-aware JSON REST API for transactional email, consent-based marketing, domains, templates, receiving, webhooks, and access management. 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. 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. Workspace keys send X-NoticeAPI-Project-ID for project-local endpoints. If a key can access several projects and the request does not choose one, NoticeAPI returns 403 project_required; a disallowed choice returns project_not_allowed.
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.
| Field | Type | Description |
|---|---|---|
email:send | scope | Send, batch send, email status, cancel, and reschedule. |
projects:read | scope | List and inspect projects visible to the key. |
projects:write | scope | Create, update, pause, and archive projects. |
api-keys:write | scope | List key metadata, create narrower grants, and revoke keys. |
domains:read | scope | List and inspect sending domains. |
domains:write | scope | Create, verify, and remove sending domains. |
templates:write | scope | Create, list, update, delete, and seed templates. |
audiences:write | scope | Create audiences and manage opted-in contacts. |
broadcasts:write | scope | Create, schedule, cancel, inspect, and send broadcasts. |
automations:write | scope | Create and manage audience-triggered automations. |
suppressions:write | scope | List, add, and remove suppressions. |
receiving:read | scope | Read received emails and attachments. |
receiving:write | scope | Create, verify, list, and remove receiving domains. |
webhooks:write | scope | Create, list, update, and remove signed webhook endpoints. |
{
"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
Send endpoints accept 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.
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
Projects, keys, and domains
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/projects | projects:read | List projects visible to the key. |
| POST | /api/v1/projects | projects:write | Create a project in the workspace. |
| GET/PATCH/DELETE | /api/v1/projects/:id | projects:read/write | Inspect, update, pause, or archive a project. |
| GET | /api/v1/api-keys | api-keys:write | List key metadata without secrets. |
| POST | /api/v1/api-keys | api-keys:write | Create a key no broader than the caller. |
| GET/DELETE | /api/v1/api-keys/:id | api-keys:write | Inspect a grant or revoke a key immediately. |
| GET/POST | /api/v1/domains | domains:read/write | List or create sending domains. |
| GET/DELETE | /api/v1/domains/:id | domains:read/write | Inspect or remove a sending domain. |
| POST | /api/v1/domains/:id/verify | domains:write | Check sending-domain DNS. |
Request fields: Projects, keys, and domains docs
Transactional email
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| POST | /api/v1/email/send | email:send | Send one email now or schedule it with sendAt. |
| POST | /api/v1/email/batch | email:send | Send up to 100 transactional emails in one request. |
| GET | /api/v1/emails/:id | email:send | Read status, stored body, and per-recipient events. |
| POST | /api/v1/emails/:id/cancel | email:send | Cancel a scheduled transactional email. |
| POST | /api/v1/emails/:id/reschedule | email:send | Move a scheduled transactional email. |
Request fields: Transactional email docs
Templates
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/templates | templates:write | List stored templates. |
| POST | /api/v1/templates | templates:write | Create a reusable subject/html/text template. |
| GET | /api/v1/templates/:id | templates:write | Fetch one template. |
| PATCH | /api/v1/templates/:id | templates:write | Update a template. |
| DELETE | /api/v1/templates/:id | templates:write | Delete a template. |
| POST | /api/v1/templates/starters | templates:write | Seed the starter templates again. |
Request fields: Templates docs
Audiences and broadcasts
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/audiences | audiences:write | List audiences. |
| POST | /api/v1/audiences | audiences:write | Create an audience. |
| GET | /api/v1/audiences/:id | audiences:write | Fetch one audience and contact counts. |
| DELETE | /api/v1/audiences/:id | audiences:write | Delete an audience. |
| GET | /api/v1/audiences/:id/contacts | audiences:write | List contacts in an audience. |
| POST | /api/v1/audiences/:id/contacts | audiences:write | Create or update an opted-in contact. |
| GET | /api/v1/audiences/:id/contacts/:contactId | audiences:write | Fetch one contact. |
| PATCH | /api/v1/audiences/:id/contacts/:contactId | audiences:write | Update name fields or subscribed state. |
| DELETE | /api/v1/audiences/:id/contacts/:contactId | audiences:write | Remove a contact from an audience. |
| GET | /api/v1/broadcasts | broadcasts:write | List broadcasts. |
| POST | /api/v1/broadcasts | broadcasts:write | Create an audience broadcast draft. |
| GET | /api/v1/broadcasts/:id | broadcasts:write | Fetch one broadcast and delivery stats. |
| DELETE | /api/v1/broadcasts/:id | broadcasts:write | Delete a draft or scheduled broadcast. |
| POST | /api/v1/broadcasts/:id/send | broadcasts:write | Send a draft broadcast to subscribed contacts. |
| POST | /api/v1/broadcasts/:id/schedule | broadcasts:write | Schedule or reschedule a broadcast. |
| POST | /api/v1/broadcasts/:id/cancel | broadcasts:write | Cancel a scheduled broadcast. |
Request fields: Audiences and broadcasts docs
Automations
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/automations | automations:write | List audience-triggered sequences. |
| POST | /api/v1/automations | automations:write | Create an automation. |
| GET | /api/v1/automations/:id | automations:write | Fetch one automation and recent runs. |
| PATCH | /api/v1/automations/:id | automations:write | Update steps, sender, tracking, or enabled state. |
| DELETE | /api/v1/automations/:id | automations:write | Delete an automation. |
Request fields: Automations docs
Suppressions
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/suppressions | suppressions:write | List suppressed recipients. |
| POST | /api/v1/suppressions | suppressions:write | Add a suppression manually. |
| DELETE | /api/v1/suppressions | suppressions:write | Remove a suppression after a confirmed re-opt-in. |
Request fields: Suppressions docs
Receiving
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/receiving/domains | receiving:write | List receiving domains. |
| POST | /api/v1/receiving/domains | receiving:write | Create a custom or managed receiving domain. |
| GET | /api/v1/receiving/domains/:id | receiving:write | Fetch one receiving domain. |
| POST | /api/v1/receiving/domains/:id/verify | receiving:write | Check required TXT and MX records. |
| DELETE | /api/v1/receiving/domains/:id | receiving:write | Remove a receiving domain. |
| GET | /api/v1/receiving/emails | receiving:read | List received messages. |
| GET | /api/v1/receiving/emails/:id | receiving:read | Fetch a received message body and headers. |
| GET | /api/v1/receiving/emails/:id/attachments | receiving:read | List attachment metadata. |
| GET | /api/v1/receiving/emails/:id/attachments/:attachmentId | receiving:read | Download attachment bytes. |
Request fields: Receiving docs
Webhooks
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/webhooks | webhooks:write | List project webhook endpoints. |
| POST | /api/v1/webhooks | webhooks:write | Create a signed HTTPS endpoint. |
| PATCH | /api/v1/webhooks/:id | webhooks:write | Update URL or enabled state. |
| DELETE | /api/v1/webhooks/:id | webhooks:write | Delete an endpoint. |
Request fields: Webhooks docs
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.