Email API guide for AI builders and coding agents

Add transactional email to your application. Connect your coding agent, run a simulator test, and read the delivery record.

Create a workspace and select the project for your application.
Connect hosted MCP and grant access to that project.
Ask your agent to run the simulator task below.

First agent task

Read https://www.noticeapi.com/docs/agents and https://www.noticeapi.com/openapi.json.

Use NOTICEAPI_API_KEY. Work in NOTICEAPI_PROJECT_ID unless I name another project.
First send to delivered@simulator.noticeapi.com from demo@sandbox.noticeapi.com,
then fetch the event timeline. Do not use a real recipient until the simulator succeeds.

Confirm the simulator result before adding a real recipient. Simulator delivery proves integration behavior; it does not prove inbox delivery.

Enable production email

Verify your email address. Add and verify a sending domain. Add a card to activate production sending. Sending remains subject to quotas and abuse review.

Send your first production email to a recipient you control. Fetch its delivery record and inspect the recipient outcome. An accepted or queued send does not mean the email was delivered.

Use an API key for a headless agent

Start with a sending-only key restricted to your project. It can send transactional email and fetch delivery records. Grant additional capabilities only when your task needs them.

Field	Type	Description
`Sending only`	email:send	Send transactional email and read delivery records. Restrict the key to your application project.
`Full access`	all capabilities + projects + domains	Manage the entire workspace, including future projects. Reserve this key for tasks that require that authority.
`Custom`	selected capabilities	Choose capabilities, current projects, and domains for CI jobs, client work, or narrower agents.

A key may create another key only when it has api-keys:write, and the new key must be equal to or narrower than the caller. Secrets are shown once and revocation takes effect immediately.

Connect the API key

.env.local

NOTICEAPI_API_KEY=ntc_xxxxxxxxxxxxxxxxxxxx
NOTICEAPI_PROJECT_ID=project_123

Use NOTICEAPI_API_KEY consistently across the Node SDK, CLI, local MCP server, CI, and framework integrations. Project-bound keys can omit NOTICEAPI_PROJECT_ID.

Capability reference

Field	Type	Description
`projects:read / projects:write`	management	Inspect projects or create, rename, pause, and archive them.
`api-keys:write`	management	List key metadata, create narrower keys, and revoke keys.
`domains:read / domains:write`	management	Inspect DNS status or create, verify, and remove sending domains.
`email:send`	runtime	Send, batch, schedule, cancel/reschedule, and fetch delivery timelines.
`sms:send / sms:read`	private beta	Queue SMS or read redacted activity only for an invited project. Live delivery still needs separate sender, consent, wallet, and carrier gates.
`sms:manage / sms:billing:read`	private beta	Prepare carrier-dossier and consent records or inspect the prepaid wallet; these scopes do not activate live sending.
`templates:write`	content	Manage reusable templates and starter templates.
`audiences:write`	marketing	Manage opted-in audiences and contacts.
`broadcasts:write / automations:write`	marketing	Create and operate consent-based broadcasts and automations.
`receiving:read / receiving:write`	inbound	Read inbound API messages or manage receiving domains.
`webhooks:write / suppressions:write`	operations	Manage signed event delivery and recipient blocks.

Project selection

A project-bound key always uses its project. A workspace key sets X-NoticeAPI-Project-ID; the SDK uses new NoticeAPI(key, { projectId }). For send and batch-send calls, the agent may omit the project ID: NoticeAPI uses the verified from domain's owning project and checks it against the key's scope. Other ambiguous project-local calls return project_required instead of guessing.

Machine-readable boundaries

error handling

switch (error.code) {
  case "project_required":       // choose X-NoticeAPI-Project-ID
  case "project_not_allowed":    // stop; the key cannot use it
  case "domain_not_allowed":     // stop; choose an allowed sender domain
  case "insufficient_scope":     // stop; do not retry a permission boundary
  case "recipient_suppressed":   // stop; do not work around suppression
  case "rate_limited":           // wait for Retry-After
}

Branch on stable code values, not human messages. Permission and policy failures are stop conditions. For transient 429 responses, respect Retry-After. Give each transactional task an idempotency key so retries return the original result.

Platform guardrails still apply

The API key is the operation authority; NoticeAPI does not insert a second confirmation gate. It still blocks cross-project access, disallowed domains, suppressed recipients, over-quota sends, paused accounts, and prohibited use. Broadcasts and automations always preserve unsubscribe behavior and only target subscribed contacts. SMS remains invite-only private beta and is subject to its separate consent, sender, wallet, and carrier gates. Cold outreach, scraped lists, and purchased lists are prohibited.

Connect through the hosted or local MCP server, install the Node SDK and CLI, or build directly from the OpenAPI contract.