MCP-ready email tools

NoticeAPI does not ship a native MCP server yet. The REST API is intentionally agent-friendly today: bearer auth, JSON payloads, stable error codes, idempotent sends, scoped keys, webhooks, and simulator addresses. Use this page as the tool contract for an MCP server, internal tool wrapper, or agent framework.

For the full endpoint map, see the REST API reference. For key creation and least-privilege guidance, see AI agents and scoped keys.

Recommended agent keys

Field	Type	Description
`Notification agent`	email:send	Send one-off transactional notifications and fetch status.
`Support reader`	receiving:read	Read inbound messages after email.received webhooks.
`Suppression helper`	suppressions:write	Add or remove suppressions after explicit review.
`Lifecycle operator`	audiences:write + broadcasts:write + automations:write	Draft consent-based marketing workflows. Require human confirmation before sends.

Tool catalog

Tool	REST call	Scope	Confirmation
`notice_send_email`	`POST /api/v1/email/send`	`email:send`	Confirm for production recipients.
`notice_get_email_status`	`GET /api/v1/emails/:id`	`email:send`	No confirmation.
`notice_read_received_email`	`GET /api/v1/receiving/emails/:id`	`receiving:read`	No confirmation if the user authorized support access.
`notice_add_suppression`	`POST /api/v1/suppressions`	`suppressions:write`	Confirm when removing, or when the reason is unclear.
`notice_create_broadcast_draft`	`POST /api/v1/broadcasts`	`broadcasts:write`	No send until reviewed.
`notice_send_broadcast`	`POST /api/v1/broadcasts/:id/send`	`broadcasts:write`	Always require human confirmation.

Tool definitions

These JSON shapes are not a hosted NoticeAPI MCP manifest. They are the recommended definitions to place inside your own MCP server or agent tool layer.

notice_send_email

{
  "name": "notice_send_email",
  "description": "Send one transactional NoticeAPI email. Use only for user-authorized transactional notifications.",
  "scope": "email:send",
  "endpoint": "POST /api/v1/email/send",
  "inputSchema": {
    "type": "object",
    "required": ["from", "to", "subject"],
    "properties": {
      "from": { "type": "string", "description": "Verified sender, e.g. Acme <[email protected]>." },
      "to": { "type": "string", "description": "One recipient address." },
      "subject": { "type": "string", "maxLength": 998 },
      "html": { "type": "string" },
      "text": { "type": "string" },
      "templateId": { "type": "string" },
      "variables": { "type": "object", "additionalProperties": { "type": "string" } },
      "sendAt": { "type": "string", "description": "Optional ISO timestamp up to 30 days ahead." }
    }
  },
  "headers": {
    "Authorization": "Bearer $NOTICEAPI_AGENT_KEY",
    "Idempotency-Key": "$TASK_ID"
  }
}

notice_get_email_status

{
  "name": "notice_get_email_status",
  "description": "Fetch delivery status, stored body, and per-recipient events for one sent email.",
  "scope": "email:send",
  "endpoint": "GET /api/v1/emails/{id}",
  "inputSchema": {
    "type": "object",
    "required": ["id"],
    "properties": {
      "id": { "type": "string", "description": "NoticeAPI email id returned by notice_send_email." }
    }
  }
}

notice_read_received_email

{
  "name": "notice_read_received_email",
  "description": "Read one inbound email accepted for a verified receiving domain.",
  "scope": "receiving:read",
  "endpoint": "GET /api/v1/receiving/emails/{id}",
  "inputSchema": {
    "type": "object",
    "required": ["id"],
    "properties": {
      "id": { "type": "string", "description": "Received email id from an email.received webhook." }
    }
  }
}

notice_add_suppression

{
  "name": "notice_add_suppression",
  "description": "Suppress a recipient address after an explicit opt-out, bounce review, or support request.",
  "scope": "suppressions:write",
  "endpoint": "POST /api/v1/suppressions",
  "inputSchema": {
    "type": "object",
    "required": ["email"],
    "properties": {
      "email": { "type": "string", "format": "email" },
      "reason": { "type": "string", "description": "Short operator-visible reason." }
    }
  }
}

Agent system prompt

Pair scoped keys with explicit policy text. The platform enforces suppressions and unsubscribe behavior, but the agent should still avoid prohibited work before it reaches the API.

agent instructions

You are using NoticeAPI on behalf of an authorized account owner.

Rules:
- Send only transactional email the user explicitly asked for, or drafts the user reviewed.
- Never send cold outreach, purchased-list campaigns, scraped-list email, or CRM sequences.
- For marketing, use NoticeAPI broadcasts or automations only with opted-in audiences.
- Keep unsubscribe links and List-Unsubscribe behavior intact.
- Use simulator.noticeapi.com for tests before production recipients.
- Use one Idempotency-Key per task and do not retry suppressed, quota-blocked, or out-of-scope requests.
- Ask for human confirmation before sending a broadcast or emailing more than one external recipient.

Webhook loopback

Use NoticeAPI webhooks to close the loop: email.delivered, email.bounced, email.unsubscribed, and email.received can wake an agent or job without polling. Verify x-noticeapi-signature, enqueue the work, and fetch details through the scoped API key.

Production checklist

Start in the simulator, name each key after the agent, store the secret in the agent runtime only, use idempotency keys on sends, and revoke keys from the dashboard when a workflow is retired. Broadcasts and automations are for opted-in contacts only; cold outreach is prohibited by the acceptable use policy.