Skip to content
MailStream
API and webhooks

Connect MailStream to the rest of your stack.

A small, focused v1 API with bearer keys, and signed webhooks for the events your other tools care about.

14 days free, no card required.

MailStream · API and webhooksSample data
How it works

How api and webhooks works

  1. 1

    Create a key

    Admins create API keys in settings. Keys start with mp_live_ and are shown once.

  2. 2

    Call the API

    Create and read leads, list campaigns, add leads to a campaign, record events and add suppressions.

  3. 3

    Add a webhook

    Choose events and an endpoint in the integrations tab.

  4. 4

    Verify and act

    Check the signature and timestamp, then act on the event.

The v1 endpoints

Deliberately small.

  • GET and POST /api/v1/leads, GET /api/v1/leads/{id}
  • GET /api/v1/campaigns and POST /api/v1/campaigns/{id}/leads
  • POST /api/v1/events and POST /api/v1/suppressions
  • Bearer authentication and per-key rate limiting
The v1 endpointsSample data

Signed webhooks

Every delivery carries a signature.

  • HMAC-SHA256 over timestamp.body, sent with an x-mailpilot-timestamp header
  • Events: reply, bounce, unsubscribe, form_submit, lead_created, campaign_completed, complaint
  • Retries with backoff, up to five attempts
Signed webhooksSample data

Keys handled as secrets

A leaked database should not leak keys.

  • Only a SHA-256 hash of each key is stored
  • Shown in full once, then only a prefix
  • Admin-only management
Keys handled as secretsSample data
The numbers

What MailStream enforces, not what it promises.

Limits and rules taken straight from the product.

v1 endpoints
7Leads, campaigns, events and suppressions.
Webhook events
7Reply to complaint.
Delivery attempts
5With increasing backoff from 1 minute to 2 hours.
API key storage
SHA-256Keys are stored hashed, never in plain text.
FAQ

Questions, answered.

How do I authenticate?+

Send Authorization: Bearer mp_live_... with a key created in settings.

How do I verify a webhook?+

Compute HMAC-SHA256 of the timestamp, a dot and the raw body with your secret, then compare it with the signature header. Reject old timestamps.

What happens if my endpoint is down?+

Deliveries are retried with backoff, up to five attempts.

Is the API complete?+

No. v1 covers leads, campaigns, events and suppressions. It will grow with the product.

Try api and webhooks free for 14 days

Set up your domains, connect mailboxes and send a first campaign. Upgrade only when you are ready.

14 days, no card required.