Migration Guide — Switch from SendGrid, Mailgun, Postmark & SES

Migrate your transactional email from another provider to Ark. This guide covers API mapping, domain migration, suppression list import, and webhook reconfiguration for the four most common providers.

Migration Overview

Map your API calls

Update your sending code to use Ark’s SDK or API. See the provider-specific mapping tables below.

Configure your domain on Ark

Add your sending domain and configure , , and return path DNS records. See Domain Setup.

Import your suppression list

Export bounced/unsubscribed addresses from your old provider and import them into Ark.

Update webhooks

Reconfigure webhook endpoints to receive Ark’s event format.

Switch traffic gradually

Route a percentage of traffic through Ark, monitor deliverability, then increase to 100%.

Sending Email — API Mapping

SendGrid
Mailgun
Postmark
Amazon SES

SendGrid → Ark

SendGrid	Ark	Notes
`sgMail.send(msg)`	`client.emails.send(...)`	Direct replacement
`msg.to`	`to: [...]`	Ark uses array format
`msg.from`	`from_: "..."`	Python uses `from_` (reserved word)
`msg.subject`	`subject: "..."`	Same
`msg.html`	`html: "..."`	Same
`msg.text`	`text: "..."`	Same
`msg.categories`	`tag: "..."`	Ark uses single tag per email
`msg.customArgs`	`metadata: {...}`	Key-value pairs, max 10 keys
`msg.trackingSettings.openTracking`	`track_opens: bool`	Per-email control
`msg.trackingSettings.clickTracking`	`track_clicks: bool`	Per-email control

Before (SendGrid):

import sendgrid
from sendgrid.helpers.mail import Mail

sg = sendgrid.SendGridAPIClient(api_key="SG.xxx")

message = Mail(
    from_email="hello@yourdomain.com",
    to_emails="user@example.com",
    subject="Order Shipped",
    html_content="<p>Your order is on its way!</p>"
)
message.custom_args = {"order_id": "ord_123"}

sg.send(message)

After (Ark):

from ark import Ark

client = Ark()

client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Order Shipped",
    html="<p>Your order is on its way!</p>",
    metadata={"order_id": "ord_123"}
)

Mailgun → Ark

Mailgun	Ark	Notes
`mg.messages.create(domain, data)`	`client.emails.send(...)`	No domain parameter needed
`data.to`	`to: [...]`	Same format
`data.from`	`from_: "..."`	Python uses `from_`
`data.subject`	`subject: "..."`	Same
`data.html`	`html: "..."`	Same
`data.text`	`text: "..."`	Same
`data["o:tag"]`	`tag: "..."`	Single tag
`data["v:custom"]`	`metadata: {...}`	Structured key-value
`data["o:tracking-opens"]`	`track_opens: bool`	Same concept
`data["o:tracking-clicks"]`	`track_clicks: bool`	Same concept

Before (Mailgun):

import requests

requests.post(
    "https://api.mailgun.net/v3/yourdomain.com/messages",
    auth=("api", "key-xxx"),
    data={
        "from": "hello@yourdomain.com",
        "to": ["user@example.com"],
        "subject": "Order Shipped",
        "html": "<p>Your order is on its way!</p>",
        "v:order_id": "ord_123"
    }
)

After (Ark):

from ark import Ark

client = Ark()

client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Order Shipped",
    html="<p>Your order is on its way!</p>",
    metadata={"order_id": "ord_123"}
)

Postmark → Ark

Postmark	Ark	Notes
`client.send_email(...)`	`client.emails.send(...)`	Direct replacement
`From`	`from_: "..."`	Python uses `from_`
`To`	`to: [...]`	Ark uses array
`Subject`	`subject: "..."`	Same
`HtmlBody`	`html: "..."`	Renamed
`TextBody`	`text: "..."`	Renamed
`Tag`	`tag: "..."`	Same concept
`Metadata`	`metadata: {...}`	Same concept
`TrackOpens`	`track_opens: bool`	Same
`TrackLinks`	`track_clicks: bool`	Renamed
`MessageStream`	`tenant_id: "..."`	Ark uses tenants for isolation

Before (Postmark):

from postmarker.core import PostmarkClient

postmark = PostmarkClient(server_token="xxx")

postmark.emails.send(
    From="hello@yourdomain.com",
    To="user@example.com",
    Subject="Order Shipped",
    HtmlBody="<p>Your order is on its way!</p>",
    Tag="order_notification",
    Metadata={"order_id": "ord_123"},
    MessageStream="outbound"
)

After (Ark):

from ark import Ark

client = Ark()

client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Order Shipped",
    html="<p>Your order is on its way!</p>",
    tag="order_notification",
    metadata={"order_id": "ord_123"}
)

Amazon SES → Ark

SES	Ark	Notes
`ses.send_email(...)`	`client.emails.send(...)`	Much simpler API
`Source`	`from_: "..."`	Renamed
`Destination.ToAddresses`	`to: [...]`	Flattened
`Destination.CcAddresses`	`cc: [...]`	Same concept
`Destination.BccAddresses`	`bcc: [...]`	Same concept
`Message.Subject.Data`	`subject: "..."`	Flattened
`Message.Body.Html.Data`	`html: "..."`	Flattened
`Message.Body.Text.Data`	`text: "..."`	Flattened
`Tags`	`metadata: {...}`	Simplified
`ConfigurationSetName`	Not needed	Ark handles routing

Before (SES):

import boto3

ses = boto3.client("ses", region_name="us-east-1")

ses.send_email(
    Source="hello@yourdomain.com",
    Destination={"ToAddresses": ["user@example.com"]},
    Message={
        "Subject": {"Data": "Order Shipped"},
        "Body": {
            "Html": {"Data": "<p>Your order is on its way!</p>"},
            "Text": {"Data": "Your order is on its way!"}
        }
    },
    Tags=[{"Name": "order_id", "Value": "ord_123"}]
)

After (Ark):

from ark import Ark

client = Ark()

client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Order Shipped",
    html="<p>Your order is on its way!</p>",
    text="Your order is on its way!",
    metadata={"order_id": "ord_123"}
)

Domain Migration

Keep Your Existing Domain

You can use the same sending domain with Ark. The key DNS changes:

Record	What Changes
	Replace old provider’s `include:` with `include:spf.arkhq.io`
	Add Ark’s DKIM record (different selector: `ark._domainkey`)
Return Path	Update CNAME to point to `rp.arkhq.io`
	No changes needed if already configured

Update SPF — don’t duplicate. You can only have one SPF TXT record per domain. Replace your old provider’s include with Ark’s, or add both includes to the same record if running in parallel during migration.Example: v=spf1 include:spf.arkhq.io include:sendgrid.net ~all (during migration, then remove the old provider after cutover).

See the Domain Setup guide for complete DNS configuration instructions.

Import Suppression List

Export your suppression/bounce list from your old provider and import it into Ark to avoid sending to known-bad addresses:

Python
Node.js
cURL

from ark import Ark
import csv

client = Ark()

def import_suppressions(csv_file: str):
    """Import suppression list from CSV (email,reason columns)."""
    suppressions = []

    with open(csv_file) as f:
        reader = csv.DictReader(f)
        for row in reader:
            suppressions.append({
                "email": row["email"],
                "reason": row.get("reason", "imported")
            })

    # Bulk import in batches of 100
    for i in range(0, len(suppressions), 100):
        batch = suppressions[i:i+100]
        client.suppressions.bulk_create(
            suppressions=batch
        )
        print(f"Imported {min(i+100, len(suppressions))}/{len(suppressions)}")

# Export from your old provider, then:
import_suppressions("sendgrid_suppressions.csv")

import Ark from 'ark';
import fs from 'fs';
import { parse } from 'csv-parse/sync';

const client = new Ark();

async function importSuppressions(csvFile: string) {
  const content = fs.readFileSync(csvFile, 'utf-8');
  const records = parse(content, { columns: true });

  // Bulk import in batches of 100
  for (let i = 0; i < records.length; i += 100) {
    const batch = records.slice(i, i + 100).map((row: any) => ({
      email: row.email,
      reason: row.reason || 'imported',
    }));

    await client.suppressions.bulkCreate({
      suppressions: batch,
    });

    console.log(`Imported ${Math.min(i + 100, records.length)}/${records.length}`);
  }
}

await importSuppressions('sendgrid_suppressions.csv');

# Bulk import suppressions
curl -X POST https://api.arkhq.io/v1/suppressions/bulk \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suppressions": [
      {"email": "bounced@example.com", "reason": "imported"},
      {"email": "invalid@example.com", "reason": "imported"},
      {"email": "complained@example.com", "reason": "imported"}
    ]
  }'

Export Guides by Provider

Export from SendGrid

Go to Suppressions in the SendGrid dashboard
Export each list: Bounces, Blocks, Invalid Emails, Spam Reports
Combine into a single CSV with email and reason columns
Import using the script above

Export from Mailgun

Use the Mailgun API: GET /v3/{domain}/bounces
Also export: GET /v3/{domain}/complaints and GET /v3/{domain}/unsubscribes
Combine results into a CSV
Import using the script above

Export from Postmark

Go to Suppressions in the Postmark dashboard
Click Export to download the suppression list
The CSV format is compatible — just rename columns if needed
Import using the script above

Export from Amazon SES

SES doesn’t have a bulk export. Use the API: ListSuppressedDestinations
Page through all results and save to CSV
Import using the script above

# Export from SES
import boto3
import csv

ses = boto3.client("sesv2")
suppressions = []
next_token = None

while True:
    params = {"Reasons": ["BOUNCE", "COMPLAINT"]}
    if next_token:
        params["NextToken"] = next_token

    response = ses.list_suppressed_destinations(**params)
    suppressions.extend(response["SuppressedDestinationSummaries"])
    next_token = response.get("NextToken")
    if not next_token:
        break

with open("ses_suppressions.csv", "w") as f:
    writer = csv.DictWriter(f, fieldnames=["email", "reason"])
    writer.writeheader()
    for s in suppressions:
        writer.writerow({
            "email": s["EmailAddress"],
            "reason": s["Reason"].lower()
        })

Webhook Migration

Ark’s webhook events map to other providers’ events:

Ark Event	SendGrid	Mailgun	Postmark	SES
`MessageSent`	`delivered`	`delivered`	`Delivery`	`Delivery`
`MessageDelayed`	`deferred`	`temporary-failure`	—	—
`MessageDeliveryFailed`	`bounce`	`permanent-failure`	`Bounce`	`Bounce`
`MessageBounced`	`bounce`	`permanent-failure`	`Bounce`	`Bounce`
`MessageLoaded`	`open`	`opened`	`Open`	`Open`
`MessageLinkClicked`	`click`	`clicked`	`Click`	`Click`

See Webhook Overview for full payload documentation and multi-language handler examples.

Gradual Traffic Migration

Don’t switch 100% of traffic at once. Migrate gradually to catch issues early and warm up your Ark sending reputation.

Recommended Schedule

Day	Ark Traffic	Old Provider	What to Monitor
1-3	10%	90%	Delivery rates, bounce rates
4-7	25%	75%	Spam folder placement, open rates
8-14	50%	50%	All metrics stable
15-21	75%	25%	Confirm no regressions
22+	100%	0%	Decommission old provider

Implementation Pattern

Python
Node.js

import random
from ark import Ark

ark_client = Ark()
ARK_TRAFFIC_PERCENTAGE = 25  # Increase gradually

def send_email(from_addr, to, subject, html, **kwargs):
    """Route traffic between providers during migration."""
    if random.randint(1, 100) <= ARK_TRAFFIC_PERCENTAGE:
        # Send via Ark
        return ark_client.emails.send(
            from_=from_addr,
            to=to,
            subject=subject,
            html=html,
            **kwargs
        )
    else:
        # Send via old provider
        return old_provider_send(from_addr, to, subject, html, **kwargs)

import Ark from 'ark';

const arkClient = new Ark();
const ARK_TRAFFIC_PERCENTAGE = 25; // Increase gradually

async function sendEmail(params: EmailParams) {
  if (Math.random() * 100 < ARK_TRAFFIC_PERCENTAGE) {
    // Send via Ark
    return arkClient.emails.send({
      from: params.from,
      to: params.to,
      subject: params.subject,
      html: params.html,
    });
  } else {
    // Send via old provider
    return oldProviderSend(params);
  }
}

Migration Checklist

Use this checklist to track your migration progress:

Next Steps

Domain Setup

Configure DKIM, SPF, and DMARC for your sending domains

Quickstart

Send your first email with Ark in 5 minutes

Architecture Overview

Set up white-label email for your SaaS platform

Deliverability

Best practices for inbox placement during migration

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

Migration Guide — Switch from SendGrid, Mailgun, Postmark & SES

Migration Overview

Sending Email — API Mapping

SendGrid → Ark

Mailgun → Ark

Postmark → Ark

Amazon SES → Ark

Domain Migration

Keep Your Existing Domain

Import Suppression List

Export Guides by Provider

Webhook Migration

Gradual Traffic Migration

Recommended Schedule

Implementation Pattern

Migration Checklist

Next Steps

Domain Setup

Quickstart

Architecture Overview

Deliverability

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

​Migration Overview

​Sending Email — API Mapping

​SendGrid → Ark

​Mailgun → Ark

​Postmark → Ark

​Amazon SES → Ark

​Domain Migration

​Keep Your Existing Domain

​Import Suppression List

​Export Guides by Provider

​Webhook Migration

​Gradual Traffic Migration

​Recommended Schedule

​Implementation Pattern

​Migration Checklist

​Next Steps

Domain Setup

Quickstart

Architecture Overview

Deliverability

Migration Overview

Sending Email — API Mapping

SendGrid → Ark

Mailgun → Ark

Postmark → Ark

Amazon SES → Ark

Domain Migration

Keep Your Existing Domain

Import Suppression List

Export Guides by Provider

Webhook Migration

Gradual Traffic Migration

Recommended Schedule

Implementation Pattern

Migration Checklist

Next Steps