> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Overview & Strategy

> A comprehensive guide and checklist for seamlessly migrating your email infrastructure to Mailofly with zero downtime and preserved deliverability.

# Migrating to Mailofly

Whether you are scaling past rate limits, cutting exorbitant per-contact marketing fees, escaping complex legacy APIs, or looking for unified multi-account sending and developer-friendly tooling, migrating to Mailofly is straightforward.

This guide outlines a **proven 5-phase migration framework** to switch your transactional, marketing, and broadcast email pipelines without losing delivery status data, missing inbound emails, or triggering spam filters.

***

## Migration Framework at a Glance

```mermaid theme={null}
flowchart LR
    Phase1["1. Pre-Flight Audit"] --> Phase2["2. DNS & Identities"]
    Phase2 --> Phase3["3. Audience & Suppressions"]
    Phase3 --> Phase4["4. Dual-Sending & Cutover"]
    Phase4 --> Phase5["5. Warm-up & Monitoring"]
```

***

## Phase 1: Pre-Flight Audit

Before touching code or changing DNS records, audit your existing setup:

1. **Inventory Senders & Domains**: Identify every root domain and subdomain sending email, their current SPF, DKIM, and DMARC settings, and custom tracking domains.
2. **Catalog Email Types**:
   * **Transactional**: Password resets, OTPs, receipts, account notifications (high urgency, high open rate).
   * **Broadcasts / Newsletters**: Marketing campaigns, product updates, scheduled digests.
   * **Inbound / Receiving**: Inbound webhooks, support desk addresses, catch-all forwarders.
3. **Audit Templates & Variables**: List dynamic templates, merge tags, and conditional logic used in transactional emails.
4. **Identify Integration Touchpoints**:
   * Official SDKs (`@sendgrid/mail`, `resend`, `postmark`, `boto3`)
   * SMTP relays (WordPress, Laravel, Supabase, Nodemailer)
   * Webhook listeners (handling bounces, delivery confirmations, clicks)

***

## Phase 2: Domain Verification & Sending Identities

Mailofly allows you to verify your domains with modern 2048-bit DKIM keys and SPF alignment without breaking your existing provider.

**1. Add Your Domain to Mailofly**

Navigate to **[Domains](https://www.mailofly.com/user/domains)** in your dashboard and click **Add Domain**. Enter your domain (e.g. `mail.example.com` or `example.com`).

**2. Configure DNS Records**

Add the generated DKIM (`CNAME` or `TXT`), SPF (`TXT`), and Return-Path records to your DNS provider (Cloudflare, Route 53, GoDaddy, etc.).

> [!TIP]
>
> **Coexistence Tip**: Mailofly's DKIM selector is unique (`mailofly._domainkey.yourdomain.com`). It will **never** collide with your existing provider's DKIM selectors (such as `s1._domainkey` or `resend._domainkey`), allowing both services to sign valid emails simultaneously during migration.

**3. Configure Sending Identities**

Set up **Identities** for different apps, environments, or teams (e.g., `Billing <billing@example.com>`, `Support <support@example.com>`).

***

## Phase 3: Export Suppressions & Audiences

> [!WARNING]
>
> **Deliverability Rule #1**: Never send to an address that bounced or marked your previous emails as spam. Doing so will immediately harm your domain reputation with Gmail, Yahoo, and Outlook.

1. **Export Suppressions from Old Provider**:
   * **Hard Bounces**: Invalid addresses or rejected mailboxes.
   * **Spam Complaints / Abuse Reports**: Users who clicked "Report Spam".
   * **Unsubscribes**: Contacts who opted out of promotional communications.
2. **Import Suppressions into Mailofly**:
   * Navigate to **[Audiences > Suppressions](https://www.mailofly.com/user/audience)** or use the Bulk Suppressions API.
3. **Migrate Active Contacts**:
   * Export verified active subscribers from your previous platform.
   * Import contacts into Mailofly using CSV import or the Audience API, mapping custom properties and subscription topics.

***

## Phase 4: Dual-Sending & Gradual Cutover

Avoid a high-risk "all-at-once" switch. Instead, roll out Mailofly incrementally:

> [tab] Feature-by-Feature (Recommended)
>
> Migrate one category of email at a time:
>
> 1. **Low-Risk Transactional**: Start with verification emails, internal system alerts, or receipts.
> 2. **Core Transactional**: Move password resets, authentication emails, and order confirmations.
> 3. **Scheduled Broadcasts**: Transition marketing campaigns and weekly digests.
> 4. **Inbound Processing**: Update MX records or forwarders for receiving.

> [tab] Canary / Percentage Rollout
>
> If your application dispatches high volumes through a centralized mail helper:
>
> ```ts theme={null}
> // Example: Feature flag or percentage-based canary rollout
> async function sendAppEmail(options: EmailOptions) {
>   const shouldUseMailofly = Math.random() < 0.25; // 25% to Mailofly
>
>   if (shouldUseMailofly) {
>     return await mailoflyClient.emails.send(options);
>   } else {
>     return await legacyClient.send(options);
>   }
> }
> ```
>
> Gradually increase the percentage from 10% → 25% → 50% → 100% as you verify deliverability.

> [tab] SMTP Drop-in Replacement
>
> If your software uses SMTP (e.g. Supabase, Ghost, WordPress, Laravel, or Django), simply update your environment variables:
>
> ```env theme={null}
> # Legacy Provider
> # SMTP_HOST=smtp.sendgrid.net
> # SMTP_USER=apikey
> # SMTP_PASS=SG.old_key...
>
> # Mailofly SMTP Gateway
> SMTP_HOST=smtp.mailofly.com
> SMTP_PORT=587
> SMTP_USER=mailofly
> SMTP_PASS=mf_live_xxxxxxxxxxxxxxxxxxxxxxxx
> ```

***

## Phase 5: Warm-up & Post-Migration Monitoring

If you send over 10,000 emails per day or are sending from a brand-new subdomain, observe the [Domain & IP Warm-up Guide](/docs/guides/deliverability/warm-up-guide.md):

* **Keep Hard Bounces \< 2%**: Watch your bounce rates in real time on the [Mail Logs](https://www.mailofly.com/user/emails) dashboard.
* **Keep Spam Complaints \< 0.1%**: Ensure one-click unsubscribe headers (`List-Unsubscribe`) are active on all marketing messages.
* **Inspect Webhook Events**: Verify that `email.delivered`, `email.bounced`, and `email.opened` events are correctly ingested by your backend.

***

## Platform Comparison Matrix

| Feature | Mailofly | Resend | Twilio SendGrid | Mailchimp | AWS SES | Postmark |
| :- | :- | :- | :- | :- | :- | :- |
| **API Philosophy** | Modern Developer REST & SDKs | Modern Developer REST & SDKs | Legacy v3 REST API | Heavy Marketing REST API | Low-level AWS SDK / SigV4 | Message Streams REST API |
| **SDK Ecosystem** | Node.js, Python, Go, PHP, Dart, MCP | Node, Python, Go, Ruby | Node, Python, PHP, Ruby, Java, C# | Node, Python, PHP | AWS SDKs (Boto3, JS v3, etc.) | Node, Rails, .NET, PHP |
| **Multi-Identity Routing** | Built-in native accounts & keys | Team domains | Subusers (Extra cost/complex) | Not native | Multiple identities in SES | Message streams |
| **Audience & Broadcasts** | Unified in one platform | Audiences (basic) | Marketing Campaigns (addon) | Full marketing (charges for unsubscribed!) | Requires custom Pinpoint/SES setup | Broadcast streams (strict separate pricing) |
| **React Email Support** | First-class native | First-class native | Requires custom build step | Requires third-party HTML export | Requires build step | Requires build step |
| **Inbound Webhooks** | Native webhook parsing & JSON | Inbound routing | Inbound Parse Webhook | Mandrill inbound | SES → S3 → Lambda | Inbound Webhook |
| **AI & MCP Support** | Official `@mailofly/mcp` | Community | None | None | Bedrock integrations | None |

***

## Platform-Specific Migration Guides

Select your current platform for dedicated step-by-step code examples, payload mapping tables, and gotchas:

> [card] [Migrate from Resend](/docs/guides/migrations/resend.md)
>
> Drop-in SDK replacement, React Email compatibility, and Svix webhook migration.

> [card] [Migrate from SendGrid](/docs/guides/migrations/sendgrid.md)
>
> Escape nested `personalizations` JSON, migrate SMTP relays, and import suppressions.

> [card] [Migrate from Mailchimp](/docs/guides/migrations/mailchimp.md)
>
> Unify marketing & Mandrill transactional emails and eliminate contact storage fees.

> [card] [Migrate from AWS SES](/docs/guides/migrations/aws-ses.md)
>
> Replace complex SNS/SQS/Lambda pipelines with streamlined REST endpoints and built-in logs.

> [card] [Migrate from Postmark](/docs/guides/migrations/postmark.md)
>
> Convert message streams and server tokens into Mailofly identities and API keys.

> [card] [Migrate from Mailgun](/docs/guides/migrations/mailgun.md)
>
> Transition from legacy multipart form-data to typed JSON and modern webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.