CamelMailer
DocsAPISDKsTemplatesHow-to

Migrate from SendGrid

The camelmailer-migrate tool reads your SendGrid account over the v3 API and recreates it in CamelMailer: authenticated domains, dynamic templates, and the full suppression surface. Two things move differently on purpose. SendGrid keeps your sending API key and your DKIM private key to itself, so the tool creates a fresh CamelMailer credential and a fresh per-domain DKIM key for you to publish.

What maps to what

SendGrid splits sending, authentication, and events across several surfaces. CamelMailer folds them into one server with its own domains, suppressions, templates, and webhooks.

SendGridCamelMailer
API key (SG., Authorization: Bearer)A new server API credential in the X-Server-API-Key header. SendGrid does not return existing keys over its API, so the tool mints a fresh one for you to set in your app. See Credentials.
Authenticated domain (domain authentication, DKIM CNAMEs)Sending domain with a fresh per-domain DKIM key published as a TXT record, plus SPF and a verification record. The DKIM private key stays inside SendGrid, so CamelMailer generates its own.
Dynamic templatesTemplates, created from each template's active version (subject, HTML, and plain text) through the server API.
Suppressions (bounces, blocks, spam reports, global and group unsubscribes)Suppressions per server, honored before every send.
Email Activity feedMessages imported as completed records with --history. Reads metadata only, and needs the Email Activity add-on.
Event webhookRSA-signed webhooks: MessageSent, MessageDelayed, MessageDeliveryFailed, MessageHeld. Recreate these by hand after the move.
SendGrid does not expose your existing sending API key or your DKIM private key over its API. So the migration creates a new CamelMailer credential (set it in your app) and a fresh DKIM key per domain (publish the DNS record CamelMailer shows). Everything else in the table above comes across as-is.

Run the migration

Install camelmailer-migrate and point it at SendGrid with --source sendgrid. The --source-api-key is a SendGrid API key with read access to domains, templates, and suppressions. Start with --dry-run to see the plan and the notes before anything is written.

Plan the migration (dry run)
camelmailer-migrate \
  --source sendgrid \
  --source-api-key "$SENDGRID_API_KEY" \
  --target https://app.camelmailer.com \
  --api-key "$CAMELMAILER_API_KEY" \
  --org acme \
  --dry-run

The target URL decides the rest. A *.camelmailer.com host is the hosted cloud and needs --org; any other host is a self-hosted install that uses the machine admin key. Drop --dry-run to run it.

Message history

Pass --history to import past messages from the SendGrid Email Activity feed. That feed is a paid add-on, so the tool reads it when it is enabled and prints a note and moves on when it is not. The feed returns delivery metadata, not the original message body, so history carries synthesized headers. Use --history-bodies index to keep the import to a searchable record per message.

Include message history
camelmailer-migrate \
  --source sendgrid \
  --source-api-key "$SENDGRID_API_KEY" \
  --target https://mail.example.com \
  --api-key "$CAMELMAILER_ADMIN_API_KEY" \
  --history --history-bodies index

History is imported in batches (--history-batch, default 200) after the configuration. Nothing is ever re-delivered.

SMTP drop-in

If your app already posts to SendGrid over SMTP, CamelMailer is a straight relay. Create an SMTP-type credential on the server and use its key as the password:

SMTP settings
Host:  the SMTP hostname of your CamelMailer installation
Port:  587 (STARTTLS) or 25 (plain with STARTTLS); 465 for implicit TLS
Auth:  AUTH PLAIN or AUTH LOGIN
User:  any value (accepted but unused for these mechanisms)
Pass:  an SMTP-type credential key from the server

SMTP submission reaches the same pipeline as the HTTP API. See SMTP for the session details.

Cutover checklist

  • Run --source sendgrid --dry-run and read the plan and the notes it prints.
  • Run it for real. The tool creates the server, domains, a fresh credential, templates, and suppressions.
  • Set the new server API credential in your application, replacing the SendGrid key.
  • Publish each domain's verification, SPF, and DKIM records, then verify the domain and confirm the health check is green.
  • Recreate your event webhook and map the event names.
  • Optionally re-run with --history if you have the Email Activity add-on.
  • Send a test message and confirm it is accepted and delivered.
  • Flip traffic, then keep the SendGrid account warm briefly before you close it.
Next steps: Sending email for the full send path, Credentials & routes for API and SMTP keys, and Sending domains for DNS and DKIM.