AI assistant and marketing suite, included on every plan
MailStrap

Developers

API reference

A single REST API over everything in your workspace: send and read mail, manage domains and mailboxes, and drive audiences, campaigns and automations. JSON in, JSON out, one API key. Included on every plan at no extra cost.

Getting started

Every endpoint lives under this base URL and returns JSON.

https://api.mailstrap.com/v1

Create a key in Settings → API keys. The secret is shown once, so store it somewhere safe. Here is a complete first request:

curl https://api.mailstrap.com/v1/mailboxes \
  -H "Authorization: Bearer mf_live_your_key_here" \
  -H "Accept: application/json"

Authentication

Send your key as a bearer token on every request. Keys are scoped to one organization and act with owner-level access, so treat them like a password: never ship one in client-side code or a mobile app.

Authorization: Bearer mf_live_...

Revoking a key in Settings takes effect immediately. Each key records when it was last used, so you can spot ones that are no longer needed.

Errors and limits

Standard HTTP status codes. Failures include a human-readable message, and validation failures add a field-keyed errors object.

401  Missing, invalid, or revoked API key
403  Authenticated, but not allowed to touch that resource
404  Not found, or not inside your organization
422  Validation failed (see "errors")
429  Rate limited, or your plan's monthly send ceiling was hit

Sending is bounded by your plan's monthly email allowance. Beyond the included volume, extra sends are billed as overage; beyond the plan ceiling, shared-pool sends stop until the next cycle or until the domain moves to a dedicated IP. See pricing.

Mailboxes

Create and manage mailboxes on your domains, plus aliases, forwarders, signatures and vacation replies.

GET/mailboxesList every mailbox you can access.
POST/mailboxesCreate a mailbox on one of your domains.
GET/mailboxes/{id}Fetch a single mailbox.
PATCH/mailboxes/{id}Rename, change quota, or update settings.
DELETE/mailboxes/{id}Delete a mailbox and free its address.
GET/mailboxes/{id}/aliasesList aliases.
POST/mailboxes/{id}/aliasesAdd an alias address.
GET/mailboxes/{id}/forwardersList forwarding rules.
POST/mailboxes/{id}/forwardersForward mail to another address.
GET/mailboxes/{id}/connectionIMAP and SMTP settings for mail clients.

Sending mail

Send transactional or one-off mail from any mailbox you have Send access to.

POST/messagesSend an email. Multipart form data if you attach files.

Send from any mailbox you have Send or Full access to. Use multipart form data when attaching files.

curl -X POST https://api.mailstrap.com/v1/messages \
  -H "Authorization: Bearer mf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "from_mailbox_id": "019f74dd-2933-710b-afe4-18daedf57b1f",
    "to": "customer@example.com",
    "subject": "Your order shipped",
    "body": "Tracking number: 1Z999AA10123456784"
  }'

Reading mail

Read the unified inbox: threads across every mailbox, message bodies, and attachments.

GET/threads?folder=inboxList threads in a folder (inbox, sent, archive, spam, trash).
GET/threads/{id}/body?mailbox_id=…Full message body plus real From / To / Cc.
GET/threads/{id}/attachmentDownload an attachment.
GET/mailboxes/{id}/foldersList folders, including custom ones.

Domains

Connect domains, read the DNS records we need, and verify them.

GET/domainsList your domains and their status.
POST/domainsConnect a new domain.
GET/domains/{id}/dnsThe exact MX, SPF, DKIM and DMARC records to publish.
POST/domains/{id}/verifyRe-check DNS and activate the domain.
POST/domains/{id}/cloudflarePublish the records automatically via Cloudflare.

Audiences and campaigns

Grow lists and send newsletters. Subscribers, audiences and automations are uncapped on every paid plan.

GET/audiencesList audiences.
POST/audiencesCreate an audience.
GET/audiences/{id}/subscribersList subscribers.
POST/audiences/{id}/subscribersAdd a subscriber. Ideal for wiring up your own signup form.
POST/audiences/{id}/importBulk import subscribers.
DELETE/audiences/{id}/subscribers/{subId}Remove a subscriber.
GET/campaignsList campaigns with open and click stats.
POST/campaignsCreate a campaign draft.
POST/campaigns/{id}/sendSend or schedule a campaign.
GET/automationsList automated journeys.
POST/automationsCreate a welcome series or drip.

Wiring your own signup form to an audience is two lines:

curl -X POST https://api.mailstrap.com/v1/audiences/{audience_id}/subscribers \
  -H "Authorization: Bearer mf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "email": "new@subscriber.com", "name": "Jane Cooper" }'

Prefer not to write code? Every audience also has a copy-paste embed form and a hosted signup page.

SMTP and IMAP

Send from your own app, or connect any mail client. Host is mail.mailstrap.com for everything. Authenticate with the full mailbox address as the username and its mailbox password. Port 465 uses implicit TLS; port 587 uses STARTTLS. Both are supported, so use whichever your library defaults to. PHPMailer users: 465 needs ENCRYPTION_SMTPS, 587 needs ENCRYPTION_STARTTLS.

SMTPmail.mailstrap.com:465Sending, implicit TLS (SSL/TLS).
SMTPmail.mailstrap.com:587Sending, STARTTLS. The common library default.
IMAPmail.mailstrap.com:993Receiving, implicit TLS.

Webhooks

Get delivery, bounce and complaint events pushed to your app instead of polling for them. Add endpoints in Settings → Webhooks, or manage them here. Every request carries an X-MailStrap-Signature header: an HMAC-SHA256 of the raw body keyed with your signing secret. Failed deliveries retry with backoff for about 12 minutes.

GET/webhooks/eventsThe catalogue of events you can subscribe to.
GET/webhooksList your endpoints.
POST/webhooksCreate an endpoint. The signing secret is returned once, here only.
PATCH/webhooks/{id}Change the URL, the event list, or pause it.
POST/webhooks/{id}/testFire a sample event and see the live response.
POST/webhooks/{id}/rotateRoll the signing secret.
DELETE/webhooks/{id}Delete an endpoint.

Contacts and tasks

The rest of the workspace.

GET/contactsEveryone you correspond with.
GET/tasksList tasks.
POST/tasksCreate a task.
PATCH/tasks/{id}Complete or update a task.

Need a hand?

Setup help is free on every plan, and that includes the API. Tell us what you are building and we will help you wire it up.

Talk to us →