Welcome to the Mailivery API – the programmatic way to connect mailboxes, automate warm-up, and monitor deliverability from inside your own product.
Why use the API?
- Embed mailbox onboarding directly in your app (Microsoft 365, Gmail, SMTP, SendGrid).
- Start, pause, or fine-tune warm-up automatically as your users’ needs change.
- Receive webhooks whenever a mailbox connects, disconnects, or hits an error.
Core concepts at a glance
| Concept | What it means |
|---|---|
| Campaign | Single mailbox connection that Mailivery warms up and monitors. |
| Warm-up | Controlled sending and replying that builds sender reputation before live cold outreach. |
| Health Score | Composite metric (infrastructure, reputation, engagement) reported as a percentage. |
| Tags | Free-form labels you can assign to campaigns for filtering and analytics. |
| Webhook | HTTP POST callback Mailivery sends to your endpoint when key events occur. |
Base URL & versioning
https://app.mailivery.io/api/v1
All endpoints in this documentation are prefixed with /api/v1. Future versions will be surfaced via a version picker in the sidebar.
Authentication
| Behavior | Detail |
|---|---|
| Header | Authorization: Bearer YOUR_API_KEY |
| Where to get a key | Sign up, subscribe to a plan, then go to Settings → Team Settings → API Access. |
| Scope | Keys are account-wide — they can access all mailboxes (campaigns) under the workspace. |
Keep your key secret. Contact us to change your key ASAP if you suspect exposure.
Rate limits & error envelope
- Rate limit: 240 requests per minute per key. Exceeding this returns HTTP 429
RATE_LIMIT_EXCEEDED. - Error format: All non-2xx responses share a simple JSON structure:
{
"code": "ERROR_CODE",
"message": "Human-readable explanation."
}