AI agents & scoped keys

Handing an agent a full-access email key is how spam incidents start. NoticeAPI keys carry an explicit scope list, enforced on every request — so a notification agent physically cannot touch your audience, and a support agent that reads inbound mail cannot send anything. Create keys from the dashboard and check only the boxes the integration needs.

Need the endpoint map? Read the REST API reference. Building an MCP wrapper? Use the MCP-ready tool contracts.

Agent patterns

Agent	Scopes	Allowed work
Notification agent	`email:send`	Send explicit transactional notices, schedule reminders, and fetch delivery status.
Support reader	`receiving:read`	Read inbound messages after email.received webhooks. Cannot send.
Template publisher	`templates:write`	Create or update approved templates from a deploy job.
Suppression helper	`suppressions:write`	Add suppressions after opt-outs, bounce review, or support requests.
Lifecycle operator	`audiences:write + broadcasts:write + automations:write`	Draft consent-based campaigns and automations. Human confirmation before send.

Scopes

Field	Type	Description
`email:send`	scope	Send + batch send, message status, cancel/reschedule scheduled sends.
`templates:write`	scope	Create, list, update, and delete templates (and seed starters).
`audiences:write`	scope	Audiences and contacts CRUD. Consent rules still apply — unsubscribed contacts stay unsubscribed.
`broadcasts:write`	scope	Create, send, schedule, and cancel broadcasts to subscribed contacts.
`automations:write`	scope	Create and manage audience-triggered sequences.
`suppressions:write`	scope	List, add, and remove suppressions.
`receiving:read`	scope	Read inbound email and attachments.
`receiving:write`	scope	Manage receiving domains.
`domains:write / webhooks:write`	scope	Reserved: sending domains and webhook endpoints are dashboard-managed today.

A key created without an explicit scope list is a full-access key. Out-of-scope calls return 403 with { "code": "insufficient_scope" } — stable and machine-readable, so an agent can recognize a permission boundary instead of retrying.

A notification agent

POST/api/v1/email/send

curl

# An agent key scoped to email:send can do exactly one thing.
curl -X POST https://www.noticeapi.com/api/v1/email/send \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-8412-notify" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Nightly import finished",
    "text": "2,113 rows imported, 0 errors."
  }'

Use an Idempotency-Key per task so agent retries can never double-send — the same key always returns the first result. Suppressions, daily caps, and deliverability autopilot apply to agent traffic exactly like any other traffic.

Out-of-scope call

# The same key calling a management endpoint is refused:
curl https://www.noticeapi.com/api/v1/broadcasts \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

# → 403 { "error": "This API key does not have the broadcasts:write scope. …",
#         "code": "insufficient_scope" }

A support agent reading inbound

curl

# A read-only support agent: list what arrived, fetch one message.
curl "https://www.noticeapi.com/api/v1/receiving/emails?limit=20" \
  -H "Authorization: Bearer ntc_xxxxxxxxxxxxxxxxxxxx"

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

Pair receiving:read with the email.received webhook to push new mail into the agent instead of polling.

Operating checklist

agent checklist

1. Create one scoped key per agent.
2. Store the ntc_ secret in the agent runtime only.
3. Test through simulator.noticeapi.com before production recipients.
4. Use one Idempotency-Key per task.
5. Stop on insufficient_scope, quota_exceeded, recipient_suppressed, and account_paused.
6. Require human confirmation before broadcasts or multi-recipient production sends.
7. Revoke keys from the dashboard when the workflow is retired.

Ground rules

Agent keys inherit every platform guardrail: broadcasts and automations only reach subscribed contacts of audiences you built, unsubscribe links and one-click headers are enforced by construction, and cold outreach is prohibited by the acceptable use policy. Give agents the narrowest scopes that work, name keys after the agent, and revoke from the dashboard the moment something misbehaves — revocation is immediate.

An MCP server is on the roadmap; the REST surface above is deliberately agent-friendly in the meantime — bearer auth, JSON everywhere, stable error codes, and tool contracts you can wrap today.