REST API reference
NoticeAPI exposes a JSON REST API for transactional email, consent-based broadcasts, templates, suppressions, receiving, and status retrieval. Use this page as the endpoint map, then follow the linked feature docs for request and response fields.
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 created in the portal under API keys and are shown once.
curl https://www.noticeapi.com/api/v1/emails/EMAIL_ID \ -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"
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. |
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. |
domains:write | scope | Reserved for sending-domain API access. Sending domains are dashboard-managed today. |
webhooks:write | scope | Reserved for webhook endpoint API access. Webhook endpoints are dashboard-managed today. |
{
"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.
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
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 a consent-based 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
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.