Welcome to the Mailivery API – the programmatic way to connect mailboxes, automate warm-up, and monitor deliverability from inside your own product.
The three things you need to do
That's it. Add a mailbox, start warm-up, choose your settings. Everything else in this reference is optional.
| Step | Where | |
|---|---|---|
| 1 | Add a mailbox | Connecting Mailboxes — Google, Microsoft 365, custom SMTP, SendGrid, or a hosted form |
| 2 | Start warm-up | Start Warm-Up — PATCH /campaigns/{id}/start-warmup |
| 3 | Choose your settings | Recommended Warm-Up Settings — if you don't know what to pick, start here |
New here? The Quick Start walks all three end to end in about five minutes.
Why use the API?
- Embed mailbox onboarding directly in your app (Google Workspace, Microsoft 365, 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.
Mailbox vs. campaign
In the Mailivery dashboard, a connected sending account is called a mailbox. In the API, the same entity is modeled as a campaign — that's why request paths use /campaigns/..., identifiers are named campaignId / campaign_id, and the response schema is Campaign. Throughout this reference, when an endpoint description says "mailbox," it refers to the same underlying record as campaignId in the URL or payload. No data difference — just two names for one thing.
Core concepts at a glance
| Concept | What it means |
|---|---|
Mailbox (API: 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 mailboxes 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. - Sending volume: emails per day is drawn from an account-wide pool, not allocated per mailbox. Check yours with Get Account Limits before provisioning at scale.
- Error format: All non-2xx responses share a simple JSON structure:
{
"code": "ERROR_CODE",
"message": "Human-readable explanation."
}
Optional add-ons
None of these are required to run warm-up:
| Custom Warm-Up Templates | Supply your own warm-up message content instead of Mailivery's |
| Yahoo Deliverability Filter | Tune Yahoo warm-up delivery at team or mailbox level |
| Inbox Placement Test | Check whether mail lands in inbox or spam |
| Blacklist Monitoring | Watch domains and IPs across major blocklists |
| Email Verification | Validate addresses individually or in bulk |