Email API Migration Guide

Build the inventory

List every current provider feature your product uses:

1. REST send endpoints.
2. SMTP credentials.
3. Templates.
4. Webhooks.
5. Suppressions.
6. Inbound routes.
7. Dedicated IPs.
8. Event metadata.
9. DMARC report processing.

Migration risk usually comes from forgotten edge workflows, not the main send call.

Prepare Postscale without switching traffic

Before changing production code:

1. Create the organization and API keys.
2. Add sending domains.
3. Publish DKIM records.
4. Add Return-Path routing.
5. Configure inbound subdomains if needed.
6. Verify webhooks in a staging environment.
7. Import suppressions.

Keep old provider DNS active during this phase.

Import suppressions before sends

Import suppression lists before staging or production traffic goes through the new provider. This prevents previously bounced, complained, or unsubscribed recipients from being mailed again during test sends.

Bring over:

1. Hard bounces.
2. Spam complaints.
3. Unsubscribes.
4. Manual blocks or invalid recipients.

Use /dashboard/suppressions to preview provider CSV exports before committing them, or use the Suppressions API directly. For the provider-by-provider checklist, see the Suppression List Migration Guide.

Port sending code

Move one message type at a time. Start with low-risk traffic like internal notifications or non-critical receipts.

For each message type, confirm:

1. From address.
2. Reply-To behavior.
3. Template variables.
4. Attachments.
5. Metadata.
6. Idempotency.
7. Delivery event mapping.

Use the sending guide for REST API patterns.

Port webhooks

Map old provider events to Postscale events. Your handler should treat webhook migration as a schema change:

1. Verify signatures with the new secret.
2. Store event ids.
3. Map message ids to internal records.
4. Handle retries idempotently.
5. Update dashboards or support tooling.

Run both old and new webhook handlers during parallel sending.

Cut over in stages

A safe sequence:

1. Internal tests.
2. Low-risk transactional messages.
3. A small percentage of production traffic.
4. Critical transactional streams.
5. Inbound routes.
6. Cleanup old provider credentials and DNS.

Pause the cutover if bounces, complaints, deferrals, or authentication failures drift from baseline.

After the cutover

For two weeks, monitor:

1. DMARC pass rate.
2. Bounce rate.
3. Complaint rate.
4. Deferrals by mailbox provider.
5. Webhook retry volume.
6. Suppression growth.

Do not remove the old provider until delayed bounces and outstanding retries are no longer useful.