Switching

The migration playbook.

How teams move to Sendlib from SendGrid, Amazon SES, Mailgun, Postmark, or SparkPost, one stream at a time, without resetting reputation or going blind. Written for the engineer and the deliverability lead who have to sign off on it.

Moving from your current provider, piece by piece.

What you use now, where it lands on Sendlib, and what actually changes for your team.

What you use today

  • Mail Send v3 API or SMTP relay
  • Dynamic templates
  • Event Webhook
  • Subusers and IP pools
  • Suppression groups

Where it lands on Sendlib

Mail Send
POST /v1/transmissions
Dynamic templates
Templates with substitution_data
Event Webhook
Signed webhooks, one event per attempt
Subusers
Tenants
IP pools
IP pools, attached to a stream

What changes

Categories become streams. Each stream gets its own lane, pool, and objective, and is reported against that objective by mailbox provider, so a campaign spike can never slow your sign-in codes.

From Amazon SES

Full mapping guide

What you use today

  • SendEmail API or the SMTP interface
  • Configuration sets
  • Event publishing to SNS, Firehose, or EventBridge
  • Account-level suppression list
  • Dedicated IPs

Where it lands on Sendlib

SendEmail
POST /v1/transmissions
Configuration sets
Streams, set per message with mail_type and tags
SNS / Firehose events
Signed webhooks straight to your endpoint
Suppression list
Suppressions, bulk import before cutover
Dedicated IPs
IP pools with a visible warmup policy

What changes

Events come to you as signed webhooks with the provider's response for every attempt, with no topics or delivery streams to run. Pacing and warmup are policies per mailbox provider that you can read and adjust.

From Mailgun

What you use today

  • Messages API or SMTP
  • Sending domains
  • Webhooks
  • Tags
  • Dedicated IPs and IP pools
  • Bounce, unsubscribe, and complaint lists

Where it lands on Sendlib

Messages API
POST /v1/transmissions
Sending domains
Verified sending domains
Webhooks
Signed webhooks with provider responses
Tags
options.tags, carried on every event
Suppression lists
Suppressions, enforced at accept

What changes

Instead of one pipe with tags on it, each kind of email runs in its own lane with its own objective. Suppression is checked when we accept the message, before it can cost you reputation.

From Postmark

What you use today

  • Email API or SMTP
  • Message streams for transactional and broadcast mail
  • Server API tokens
  • Templates
  • Webhooks

Where it lands on Sendlib

Email API
POST /v1/transmissions
Message streams
Streams: sign-in, transactional, lifecycle, promotional
Server tokens
Scoped API keys and SMTP credentials
Templates
Templates with substitution_data
Webhooks
Signed webhooks with provider responses

What changes

You already separate transactional from broadcast mail. Sendlib takes the same idea further: four kinds of stream, each with its own objective, pool, and per-provider policy, built for high volume.

From SparkPost

What you use today

  • Transmissions API or SMTP
  • Stored templates
  • Subaccounts
  • IP pools
  • Event webhooks

Where it lands on Sendlib

Transmissions
POST /v1/transmissions
Stored templates
Templates
Subaccounts
Tenants
IP pools
IP pools, attached to a stream
Event webhooks
Signed webhooks, one event per attempt

What changes

The closest model to ours: transmissions, templates, and pools map almost one to one. What you add is an objective per stream, policy per mailbox provider, and engineers who read the same timelines you do.

What usually stalls a migration, and how we handle it.

A reputation reset

You do not move everything at once. New pools warm on a policy while the incumbent carries the rest. Your domain reputation travels with your DKIM-signed domain, and the new IPs ramp on a schedule the pipeline enforces.

Going blind during cutover

Webhooks are the first thing we wire, not the last. From the first parallel message you have per-attempt timelines with provider responses, which is more than you had before you started.

Suppression gaps and duplicates

Bulk-import your bounces, complaints, and unsubscribes before any traffic moves. Suppression is enforced at accept. Idempotency keys mean a retry during the switch never double-sends.

The rewrite

Most programs move with an SMTP endpoint change or a thin adapter around one send call. Templates, tags, and metadata map directly. The event schema is the thing that changes, and it changes in your favour.

How a migration runs, one stream at a time.

Timelines are typical for a program sending tens of millions a month. Smaller programs move faster; larger ones move in more slices rather than more weeks.

  1. Prepare

    Before any traffic moves

    • Create and verify sending domains through the API. A second DKIM selector means both vendors sign in parallel.
    • Bulk-import suppressions: hard bounces, complaints, unsubscribes. Verify counts against the incumbent's export.
    • Create scoped keys per environment. send:* for services, manage:* for tooling.
    • Register a webhook endpoint and validate it with the test endpoint and the simulator before the first real event.
  2. Parallel run

    Week one

    • Pick one stream. Transactional is usual: high value, steady volume, clear success criteria.
    • Route it over SMTP submission or the transmissions API. The incumbent keeps everything else.
    • Keep both event pipelines flowing. Reconcile the same message on both sides.
  3. Compare

    Weeks two and three

    • Deferral rate and latency per provider for the same traffic, side by side.
    • Bounce explorer by provider and signature against the incumbent's bounce categories.
    • Time to answer "what happened to this message" for a support case, on each side.
  4. Warm and cut over

    Weeks three to six

    • Attach a warmup policy to the new pool and let it ramp. Progress and adjustments are visible through the API.
    • Shift the remaining streams by percentage. Promotional traffic moves last, on its own lane.
    • Keep the incumbent as a fallback route until the numbers have held for a full cycle.
  5. Decommission

    When the numbers hold

    • Retire the old DKIM selector and credentials.
    • Export the incumbent's historical events if you need them for audit. Your Sendlib log starts from the first parallel message.

Most teams start with a single configuration change.

If you already relay over SMTP, the parallel run is a hostname and a credential. If you call an API, it is a thin adapter around one send function. The data model maps directly.

SMTP relay · one stream

credentials scoped to this app

drop-in
# before
SMTP_HOST=smtp.incumbent.example
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.…

# parallel run
SMTP_HOST=smtp.sendlib.com
SMTP_PORT=2525
SMTP_USER=billing-service
SMTP_PASS=smtp_live_…

API adapter · one function

idempotent
async function send(msg, key) {
  const res = await fetch("https://api.sendlib.com/v1/transmissions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SENDLIB_API_KEY}`,
      "Idempotency-Key": key,          // safe to retry
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipients: [{ email: msg.to }],
      content: { template_id: msg.template, substitution_data: msg.vars },
      options: { mail_type: "transactional", tags: msg.tags, metadata: msg.meta },
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return (await res.json()).transmission_id;
}

How the concepts map across.

Incumbent conceptSendlib
Mail Send / SendEmail / messagesPOST /v1/transmissions
Event Webhook / SNS notifications / eventsPOST /v1/webhooks
Global suppressions / account-level suppression listPOST /v1/suppressions
Dynamic templates / templatesPOST /v1/templates
Dedicated IPs / IP poolsPOST /v1/ip-pools
Subusers / configuration setsTenants
Categories / tagsoptions.tags
Unique args / message tagsoptions.metadata
Scoped API keyssend:* and manage:* keys

Questions before you switch.

What every migration review asks, answered plainly.

Do we need to cancel our current contract first?
No. The parallel run is designed to overlap it. Your current provider keeps carrying everything except the stream you move, and stays as a fallback until the numbers have held for a full cycle.
What do we change in DNS?
Add our SPF include and a second DKIM selector. Both providers sign in parallel, so nothing breaks while you move. You retire the old selector at the end.
Will our reputation reset?
Your domain reputation travels with your DKIM-signed domain. New IPs ramp on a warmup policy per mailbox provider while your current provider carries the rest of the volume.
Can we roll back?
At any point. Moving a stream back is a hostname or one adapter change, and nothing about your current setup is removed until you decide to retire it.
What does the parallel run cost?
Only the volume that actually flows through Sendlib during the run. You are not committing to the full program until you have seen the numbers.

Plan the parallel run with an engineer.

Tell us your sending domain, monthly volume, and current provider. We come back with a stream to start with, a warmup plan for the new pool, and what we will compare.

What happens next

  1. We review the domain

    Every sender is vetted before it sends. A small, clean network is part of the product.

  2. We provision the environment

    Scoped keys, SMTP credentials, DNS records for SPF and DKIM, a webhook endpoint to test against.

  3. You move one stream

    Usually sign-in codes or receipts, measured against its objective from the first message.

We vet every sender before provisioning. If we are not the right fit for your program, we will say so.