Is Mailers.io an email provider?

No. Mailers.io is an orchestration and control layer that sits above email providers. Customers connect their own Amazon SES, Mailgun, SendGrid, Resend, Postmark, Brevo, Gmail / Google Workspace SMTP, Outlook / Microsoft 365 SMTP, or any SMTP server.

How does quota-aware routing work?

Mailers.io distributes sending across connected providers using per-provider hourly and daily caps and a priority order. When a provider approaches its cap or returns a transient error, the router automatically falls back to the next eligible provider with no code changes.

Which providers can I connect?

Amazon SES, Mailgun, SendGrid, Postmark, Resend, Brevo, Gmail / Google Workspace SMTP, Outlook / Microsoft 365 SMTP, and any RFC-compliant SMTP server. New providers are added over time.

Is there a free plan?

Yes. The Free plan is $0 forever and includes 2,500 credits per month, one connected provider, campaigns, API access, and community support. No credit card required.

Does Mailers.io support transactional and marketing emails?

Yes. Transactional sends go through the unified API. Marketing, lifecycle, and cold-email sends run via the campaigns and automations modules. Per-provider routing rules can segment reputation by use case.

How is compliance handled?

Compliance is built into the platform: global unsubscribe, List-Unsubscribe header, bounce and complaint suppression, do-not-contact lists, domain-level suppression, per-workspace suppression, and full audit logs. A signed DPA is available at https://mailers.io/dpa covering GDPR Article 28, SCCs Module 2, UK IDTA, Swiss FADP, and CCPA/CPRA service-provider terms.

Does Mailers.io include inbox or reply management?

No. Mailers.io does not sync replies or provide a unified inbox. Replies are delivered to whichever mailbox receives them on the connected provider.

Can I white-label Mailers.io?

Yes, on the Enterprise plan. White-label covers the dashboard, email surfaces (unsubscribe, preference center, tracking), and per-client sending domains.

How does authentication work?

Bearer tokens via the Authorization header. Keys are scoped per service, environment, workspace, and action. You can run multiple active keys in parallel to rotate without downtime. All authenticated requests are written to audit logs.

Does the API support idempotent sends?

Yes. Include an Idempotency-Key header (any unique string, typically a UUID) and the platform will deduplicate retries automatically. Safe to retry from workers, queues, or cron jobs without duplicating mail.

What about rate limits?

Workspace-level API rate limits scale with your plan and sending profile. The router also applies per-provider hourly and daily caps you configure. Limit headers on every response tell your client how much capacity is left.

How large can a bulk send be?

Up to 1,000 messages per /v1/send/bulk request. Larger jobs run as campaigns, which handle scheduling, batching, and provider distribution for you — with the same normalized event stream back to your webhook endpoint.

Are webhooks signed and replay-safe?

Every webhook is signed with HMAC-SHA256 and a rotating secret. Timestamps guard against replay. Delivery is retried with exponential backoff, and failed events land in a replay queue you can re-trigger by ID.

What SDKs are available?

Official SDKs for Node.js, Python, Go, PHP, and Ruby — all wrapping the same REST API. Anything not covered by an SDK is a plain HTTPS + JSON call with documented shapes.

Can I use the API without the dashboard?

Yes. The API is a first-class surface — you can operate entirely headlessly if you want. Many teams start with pure API integration and adopt the dashboard later for campaigns, lists, and team collaboration.

Does the API handle inbound email or replies?

No. Mailers.io is an outbound orchestration platform. The API is for sending, routing, audience, compliance, and analytics. Replies land in the mailboxes tied to your sending identities — not inside Mailers.io.

How do I try it before committing?

Start with a free account, create a scoped test key, and connect a single provider — SES, Mailgun, SMTP, or Gmail all work out of the box. You can run real sends through the router in a few minutes without changing any application architecture.

Developer platform

One API. Every provider you're connected to.

Integrate Mailers.io once and send across Amazon SES, Mailgun, SendGrid, Resend, SMTP, or any provider in your stack. The router picks the right provider, applies your quotas, and hands your code a predictable response every time.

Get API Key Read the Docs

JSON over HTTPS: REST
JSON over HTTPS
Typical API p95: < 50ms
Typical API p95
Messages per bulk send: 1,000
Messages per bulk send
Safe retries by default: Idempotent
Safe retries by default

Chapter 01 · Why this API

An API designed for teams that outgrow single-provider setups.

Most email APIs wrap one provider. Mailers.io wraps your whole stack — and keeps the developer surface boring in the best way: stable, normalized, and safe to retry.

One contract, every provider

POST /v1/send is the same call whether the router chooses SES, Mailgun, SendGrid, or your SMTP relay. No provider-specific branches in your code, ever.

Idempotent by design

Use an idempotency key on any send. Retries — from your workers, your queues, or the network — never duplicate mail. The API knows the difference between a retry and a fresh send.

Normalized events

Deliveries, bounces, complaints, opens, clicks, unsubscribes — all providers are mapped to one event shape. Webhook consumers stay simple as your provider mix changes.

Dashboard = API

Every action available in the UI is available via the API. Campaigns, lists, templates, automations, subscribers, suppression, analytics — all first-class endpoints.

Scoped API keys

Issue keys per service, environment, or workspace. Scope them to specific domains or actions. Rotate without downtime. Track usage per key in audit logs.

Stable, predictable responses

Documented error codes. Consistent pagination. Real status codes (not 200 OK with an error body). Provider quirks stay behind the interface — not in your exception handlers.

Chapter 02 · Send in any language

Drop it into your existing codebase in minutes.

Official SDKs for Node.js, Python, Go, PHP, and Ruby. A clean REST surface for everything else. Idempotency keys are first-class so retries never duplicate mail.

AuthBearer token · scoped keys
RetriesIdempotency-Key header
BulkUp to 1,000 messages per request
ErrorsDocumented codes, real HTTP status
WebhooksSigned, replay-safe, normalized schema

POST /v1/send

curl -X POST https://api.mailers.io/v1/send \
  -H "Authorization: Bearer $MAILERS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    "[email protected]",
    "to":      "[email protected]",
    "subject": "Welcome to Acme",
    "html":    "<p>Thanks for joining.</p>",
    "tags":    ["onboarding"],
    "routing": { "purpose": "transactional" }
  }'

Response · 202 acceptedid · routed · provider = amazon-ses · idempotency_key honored

p95

38ms

regions

3 pops

uptime

99.95%

Chapter 03 · Request lifecycle

What happens between POST and delivery.

A single call to /v1/send triggers a short, deterministic pipeline. Nothing hidden, nothing magical.

Step 01
Authenticate
Bearer token + scope check. Requests from unknown keys or unauthorized scopes are rejected before any work.
Step 02
Validate & resolve
Normalize payload, resolve sender, attach workspace context, apply idempotency if key is present.
Step 03
Route
Evaluate quota-aware routing rules, pick an eligible provider, apply priority and domain scoping.
Step 04
Suppress
Check global, domain, workspace, and list-level suppression. Blocked recipients never leave the boundary.
Step 05
Dispatch & track
Send via the chosen provider. Record events. Emit normalized webhooks as delivery milestones land.

The entire pipeline runs in a single request. Typical p95 for the API call is < 50ms — provider dispatch happens in the background and flows back to you through webhook events.

Chapter 04 · Endpoint reference

Everything the dashboard does, also through the API.

Eight resource families. Consistent shapes. No hidden dashboard-only features. If you can click it, you can script it.

Sending

POST
/v1/send
Send a single email through the router.
POST
/v1/send/bulk
Bulk send up to 1,000 messages per request.
GET
/v1/messages/:id
Fetch status and event history for one message.

Campaigns

POST
/v1/campaigns
Create or schedule a campaign.
GET
/v1/campaigns
List campaigns with pagination and status filters.
POST
/v1/campaigns/:id/launch
Launch or queue a scheduled campaign.
GET
/v1/campaigns/:id/report
Read the normalized campaign report.

Automations

POST
/v1/automations
Create an event, time, or condition-based automation.
POST
/v1/automations/:id/trigger
Trigger an automation for a specific subscriber.
GET
/v1/automations/:id/runs
Inspect automation runs and outcomes.

Templates

GET
/v1/templates
List templates with filters and pagination.
POST
/v1/templates
Create or update a reusable template.
POST
/v1/templates/:id/render
Render a template with variables for preview.

Lists & subscribers

GET
/v1/lists
List mail lists and segments.
POST
/v1/lists/:id/subscribers
Add, update, or bulk import subscribers.
DELETE
/v1/lists/:id/subscribers/:sid
Remove or unsubscribe a subscriber.

Suppression & compliance

POST
/v1/suppressions
Push unsubscribes, bounces, or complaints.
GET
/v1/suppressions
Query global and scoped suppression records.
GET
/v1/audit-logs
Read signed audit log entries.

Analytics & events

GET
/v1/analytics/events
Query raw message events with filters and time windows.
GET
/v1/analytics/summary
Aggregated deliverability and engagement metrics.
GET
/v1/webhooks
Manage webhook endpoints and signing secrets.

Infrastructure

GET
/v1/sending-servers
List connected providers and SMTP servers.
POST
/v1/sending-domains
Register and verify a sending domain.
POST
/v1/routing/rules
Manage quota-aware routing rules.

Full schema, error codes, and pagination rules live in the API reference. Every endpoint is versioned and documented.

Chapter 05 · Auth & keys

Keys that behave like infrastructure credentials.

Mailers.io treats API keys the way you already treat cloud credentials — scoped, rotatable, auditable, and isolated per workload. No global master keys sprayed across services.

Per-service keys
Issue a key for each service, environment, or workspace. Your staging worker never shares credentials with production.
Granular scopes
Restrict a key to specific actions, domains, or resources — send-only, read-only analytics, list management, and more.
Rotate without downtime
Generate a new key, deploy, then revoke the old one. Multiple active keys per workspace keep rotations safe.
Audit every call
Every authenticated request is logged. Filter by key, user, or workspace. Export to SIEM or read via the audit-logs API.

API keys · acme-workspace

4 active

prod-api-worker
send · read:messages
ml_live_7F4•••active
prod-analytics-readonly
read:analytics · read:events
ml_live_2A1•••active
staging-integration
send · read:messages · write:lists
ml_test_9C8•••active
legacy-worker
send
ml_live_4B2•••rotating

Keys are revealed once at creation time, stored hashed, and displayed as prefixes only afterwards — same posture as modern cloud credentials.

Chapter 06 · Webhooks

One event schema, every provider.

Mailers.io normalizes delivery and engagement events across every connected provider. Your webhook consumers speak one shape — whether the send routed through SES, Mailgun, SendGrid, or your own SMTP relay.

•message.accepted
•message.delivered
•message.opened
•message.clicked
•message.bounced
•message.complained
•subscriber.unsubscribed
•automation.triggered

signing

HMAC-SHA256

delivery

Retries + DLQ

order

Per-message

POST https://your-app.com/webhooks/mailerssigned

{
  "id":         "evt_01HM...",
  "type":       "message.delivered",
  "created_at": "2026-04-19T10:24:11Z",
  "workspace":  "acme",
  "message": {
    "id":        "msg_01HM...",
    "provider":  "amazon-ses",
    "from":      "[email protected]",
    "to":        "[email protected]",
    "tags":      ["onboarding"]
  },
  "signature": "t=1713516251,v1=..."
}

Response · 200 OK within 15sauto-retry with exponential backoff if non-2xx

Failed deliveries are retried with exponential backoff and pushed to a replay queue you can re-trigger from the dashboard or API. No events lost to your downtime.

API FAQ

Engineering-honest answers about the developer surface

What to expect when you plug Mailers.io into real production systems.

Yes. POST /v1/send is the same call whether the router dispatches through Amazon SES, Mailgun, SendGrid, Resend, Postmark, Gmail, Microsoft 365, or your own SMTP relay. Provider-specific quirks (headers, auth, event shapes) are handled inside the platform — not in your code.

Integrate once · Swap providers forever

One integration. A provider stack you can actually evolve.

Ship faster with a single contract. Rotate providers without redeploying. Keep your sending architecture flexible — not locked to whichever provider you picked on day one.

Get API Key See integrations

Free to start
·
REST · JSON · signed webhooks
·
SDKs for Node, Python, Go, PHP, Ruby