Give your agent an API key

NoticeAPI is designed to be operated end to end by an authorized developer agent. A key can cover the whole workspace for speed, bind permanently to one project, or carry a custom combination of capabilities, projects, and sender domains.

Choose the grant

Field	Type	Description
`Full access`	all capabilities + projects + domains	Fastest for a trusted personal agent managing the workspace. It also includes future projects, so protect the secret like an owner credential.
`Sending only`	email:send	Runtime key for transactional send/status with optional project and sender-domain restrictions.
`Custom`	selected grant	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 grant must be equal to or narrower than the caller. Secrets are shown once and revocation takes effect immediately.

Connect it

.env.local

NOTICEAPI_API_KEY=ntc_xxxxxxxxxxxxxxxxxxxx
NOTICEAPI_PROJECT_ID=project_123

agent instructions

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 [email protected] from [email protected],
then fetch the event timeline. Do not use a real recipient until the simulator succeeds.

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.

Capabilities

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 grants, 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.
`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 campaigns and sequences.
`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 }). When a key can access several projects and no project is supplied, NoticeAPI returns project_required. It never guesses across client work.

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. 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.