API reference

Public API, coming soon.

REST for reads, webhooks for events — landing with the Team plan. Generate a key in the dashboard and pipe signal into your stack. No partnership form, no "contact sales for an API key."

Authentication

Bearer keys.

Every request is authenticated with a secret key in the Authorization header. Keys are scoped per workspace and revocable from the dashboard. API + webhooks are coming with the Team plan.

GET · /v1/threads

curl https://api.mailsenseai.com/v1/threads \
  -H "Authorization: Bearer $MAILSENSEAI_KEY"

{
  "data": [
    {
      "thread_id":   "th_8m2KQ",
      "subject":     "Re: Q2 procurement — pricing addendum",
      "recipient":   "maya@northwind.co",
      "opens":       3,
      "clicks":      1,
      "replied":     false,
      "health":      82,
      "updated_at":  "2026-05-09T13:14:02Z"
    }
  ],
  "has_more": false
}

Endpoints

REST surface.

GET/v1/threadsList tracked threads with rollup signal.

GET/v1/threads/:idFull event history for a single thread.

GET/v1/eventsStream raw open / click / reply events.

POST/v1/webhooksSubscribe an endpoint to thread events.

GET/v1/webhooksList your webhook subscriptions.

DELETE/v1/webhooks/:idRemove a webhook subscription.

Webhooks

Events, pushed.

Subscribe an HTTPS endpoint and we POST a signed JSON payload the moment something happens. Retries with exponential backoff for 24 hours.

thread.opened
thread.clicked
thread.replied
recipient.opted_out

POST · /v1/webhooks

# Subscribe to thread.opened events
curl https://api.mailsenseai.com/v1/webhooks \
  -H "Authorization: Bearer $MAILSENSEAI_KEY" \
  -d url=https://hooks.acme.dev/inbound \
  -d events[]=thread.opened \
  -d events[]=thread.clicked

# You'll receive:
{
  "event":      "thread.opened",
  "thread_id":  "th_8m2KQ",
  "recipient":  "maya@northwind.co",
  "device":     "iPhone",
  "city":       "Brooklyn, NY",
  "occurred_at":"2026-05-09T13:14:02Z"
}