API tokens

Tokens authenticate your services against the content ingest endpoint, the read-only API, and the MCP server.

Tokens

No tokens yet. Create one per service so you can revoke them independently.

MCP server

Read-only Streamable HTTP endpoint for Claude Code, Cursor, and other MCP clients. Tools: search events, message timeline with bounce diagnostics, delivery stats, and suppressed-address checks.

https://demo.sesmograph.com/mcp

Claude Code

claude mcp add --transport http sesmograph https://demo.sesmograph.com/mcp \
  --header "Authorization: Bearer <token>"

Cursor and other clients (mcp.json)

{
  "mcpServers": {
    "sesmograph": {
      "url": "https://demo.sesmograph.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

REST API

Base URL https://demo.sesmograph.com/api/v1, authenticated with Authorization: Bearer <token>. Read endpoints are limited to 120 requests per minute.

GET /api/v1/events
Search events, newest first. Filters: q (recipient, subject, sender, or SES message ID), topic, type, from/to dates, page.
GET /api/v1/messages/{sesMessageId}
One message's full timeline, oldest first, including SMTP bounce diagnostics.
GET /api/v1/stats
Daily counts, totals, bounce and complaint rates from the aggregates. Params: topic, from, to (defaults to the last 30 days).
GET /api/v1/suppressed
With ?address=: is this address safe to send to. Without it: the full list, filterable by topic and reason.
POST /api/v1/messages/{sesMessageId}/content
Push the sent email's body (html, text) so it shows on the message page. Kept 30 days.
GET /api/v1/health
For uptime monitors: returns ok plus the age of the newest event. Not recorded in the activity log.

Example: check an address before sending

curl -H "Authorization: Bearer <token>" \
  "https://demo.sesmograph.com/api/v1/[email protected]"

Example: bounce rate for one topic

curl -H "Authorization: Bearer <token>" \
  "https://demo.sesmograph.com/api/v1/stats?topic=my-app&from=2026-09-27"