Mailivery API — Quick Start (5-Minute Demo)

1. Prerequisites

Item	Detail
API key	Sign up, subscribe to a plan, then go to Settings → Team Settings → API Access.
Base URL	https://app.mailivery.io/api/v1
Auth header	Authorization: Bearer YOUR_API_KEY
HTTP tool	cURL, Postman, or any client you like (examples use cURL).

---

2. Make sure your key works (10 seconds)

Bash

curl -X GET https://app.mailivery.io/api/v1/campaigns \
     -H "Authorization: Bearer $MAILIVERY_API_KEY"

• 200 OK → key is valid (list may be empty).
• 401 → check the header format.

---

3. Add a mailbox

📘

Connect endpoints use multipart/form-data, not JSON.

Send fields as form parts (-F in cURL). Field names are snake_case.

Google Workspace / Gmail — app password

The mailbox owner needs 2-Step Verification enabled and a 16-character app password.

Bash

curl -X POST https://app.mailivery.io/api/v1/campaigns/gmail \
  -H "Authorization: Bearer $MAILIVERY_API_KEY" \
  -F "first_name=Ada" \
  -F "last_name=Lovelace" \
  -F "[email protected]" \
  -F "app_password=abcdefghijklmnop" \
  -F "email_per_day=20" \
  -F "response_rate=25" \
  -F "timezone=America/Chicago"

Required: first_name, email, app_password, email_per_day, response_rate.

Google Workspace / Gmail — OAuth (no app password; invite-only, contact support to enable)

Bash

curl -X POST https://app.mailivery.io/api/v1/campaigns/google-oauth \
  -H "Authorization: Bearer $MAILIVERY_API_KEY" \
  -F "first_name=Ada" \
  -F "last_name=Lovelace" \
  -F "[email protected]" \
  -F "google_token=ya29.a0...partner-issued-access-token" \
  -F "google_refresh_token=1//0g...partner-issued-refresh-token" \
  -F "email_per_day=20" \
  -F "response_rate=25"

Required: first_name, email, google_token, google_refresh_token, email_per_day, response_rate. The refresh token must carry the full https://mail.google.com/ scope.

Other providers

Provider	Endpoint
Microsoft 365 / Outlook	POST /campaigns/ms-graph	Returns a consent URL; mailbox stays pending until the owner authorizes
Custom SMTP	POST /campaigns/smtp	Needs full SMTP and IMAP host / port / username / password
SendGrid	POST /campaigns/sendgrid
Hosted form	GET /embed/form/secure	Your users authorize without you handling credentials

All of them return 200 with a JSON body containing the new id → save it, every step below needs it.

---

4. Start warm-up

Bash

curl -X PATCH https://app.mailivery.io/api/v1/campaigns/$ID/start-warmup \
     -H "Authorization: Bearer $MAILIVERY_API_KEY"

Success message: { "message": "Warm-up started" }

For a Microsoft mailbox, call this after the owner has completed the consent flow — before that the mailbox sits in pending.

---

5. Choose your settings

Volume, ramp-up, and sending schedule decide whether warm-up actually helps. If you don't know what to set, use the defaults on Recommended Warm-Up Settings — the short version is match your intended cold-send volume (up to 50 emails/day), set response rate to your plan's maximum, and turn ramp-up on.

Note these settings endpoints take application/x-www-form-urlencoded (-d), unlike the connect endpoints above which take multipart/form-data (-F).

Bash

curl -X PATCH https://app.mailivery.io/api/v1/campaigns/$ID/update-email-per-day \
     -H "Authorization: Bearer $MAILIVERY_API_KEY" \
     -d "email_per_day=20"

That's the whole required path: add → start → settings. Everything below is optional.

---

6. (Optional) Check the health score

Bash

curl -X PATCH https://app.mailivery.io/api/v1/campaigns/$ID/get-health-score \
     -H "Authorization: Bearer $MAILIVERY_API_KEY"

You'll see DNS grade, SPF/DMARC status, and reputation signals. Call this daily to monitor progress.

---

7. What next?

Task	Endpoint
Pause / resume warm-up	/campaigns/{id}/pause-warmup, /resume-warmup
Tweak volume or reply-rate	/update-email-per-day, /update-response-rate
Fetch detailed metrics	/campaigns/{id}/get-metrics
Check your account pool	/account/limits
Receive live events	Set up Settings → Webhooks