> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailofly.com/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.

<Steps>
  <Step title="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`).
  </Step>

  <Step title="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.
    </Tip>
  </Step>

  <Step title="Configure Sending Identities">
    Set up **Identities** for different apps, environments, or teams (e.g., `Billing <billing@example.com>`, `Support <support@example.com>`).
  </Step>
</Steps>

***

## 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.
</Warning>

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:

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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
    ```
  </Tab>
</Tabs>

***

## 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](/guides/deliverability/warm-up-guide):

* **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:

<CardGroup cols={3}>
  <Card title="Migrate from Resend" icon="paper-plane" href="/guides/migrations/resend">
    Drop-in SDK replacement, React Email compatibility, and Svix webhook migration.
  </Card>

  <Card title="Migrate from SendGrid" icon="grid-2" href="/guides/migrations/sendgrid">
    Escape nested `personalizations` JSON, migrate SMTP relays, and import suppressions.
  </Card>

  <Card title="Migrate from Mailchimp" icon="envelope-open-text" href="/guides/migrations/mailchimp">
    Unify marketing & Mandrill transactional emails and eliminate contact storage fees.
  </Card>

  <Card title="Migrate from AWS SES" icon="aws" href="/guides/migrations/aws-ses">
    Replace complex SNS/SQS/Lambda pipelines with streamlined REST endpoints and built-in logs.
  </Card>

  <Card title="Migrate from Postmark" icon="bolt" href="/guides/migrations/postmark">
    Convert message streams and server tokens into Mailofly identities and API keys.
  </Card>

  <Card title="Migrate from Mailgun" icon="shield-halved" href="/guides/migrations/mailgun">
    Transition from legacy multipart form-data to typed JSON and modern webhooks.
  </Card>
</CardGroup>


## Related topics

- [Introduction](/api/index.md)
- [Migration Guide](/audience/migration-guide.md)
- [Why Use Segments?](/guides/sending/why-use-segments.md)
- [E2E testing with Playwright](/guides/testing/playwright-testing.md)