Welcome to the Mailivery API – the programmatic way to connect mailboxes, automate warm‑up, and monitor deliverability from inside your own product or scripts.
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 | A 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 for account -> Request Demo or Call (from website) |
| Scope | Keys are account‑wide — they can access all campaigns (mailboxes) under the workspace. |
Keep your key secret. Contact us to change your key ASAP if you suspect exposure.
Rate limits & error envelope
- Rate limit: 10 requests per second 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."
}