# Migration from Resend

Move transactional sends from Resend to Groundmail. Sign-in codes, receipts and alerts go out over `POST /emails` with a Bearer key, so for most apps the switch is a new base URL, a `gm_` API key and a verified domain.

**Import your Resend account (Beta).** Paste a Resend API key with Full access on the [Import page](https://app.groundmail.dev/import?provider=resend) and Groundmail imports your suppression list, templates and sending domains. Nothing changes in your Resend account, and the key is never stored. Webhooks come over when you import from the terminal or the API.

**Or from the terminal**

```bash
export RESEND_API_KEY=re_…                # a Full access key
groundmail migrate resend --dry-run       # preview: nothing is written
groundmail migrate resend                 # import
```

Groundmail brings over your **suppression list** (bounces, complaints and manual suppressions), **templates** (`{{{VARIABLE}}}` becomes `{{VARIABLE}}`, same names), **sending domains** (with the DNS records to publish, one click on Cloudflare, Vercel and GoDaddy) and, from the terminal or the API, **webhooks** (events mapped, created disabled until your handler is ready).

Use a key with **Full access**: Resend's Sending access keys can only send, so they cannot read your account. Create one under API Keys → Create API key → Permission: Full access, run the import, then delete it.

What to know:

- **Templates** that are published in Resend and have no unpublished edits are published in Groundmail under the same alias. A template that was never published, or has edits you haven't published, comes in as a draft: Resend's API returns one version and cannot say which one you send, so check it, then publish. Fallback values come across, whether written inline (`{{{NAME|there}}}`) or set on the template's variable list: each becomes a default on the variable, `{{NAME | default:"there"}}`. A template's default `from` and `reply_to` do not come across, so set them on each send.
- **Webhooks**: Resend's email events have the same names in Groundmail (`email.delivered`, `email.bounced` and so on). Contact, domain and suppression events have no Groundmail webhook and are listed as not mapped.
- **Contacts** who unsubscribed from your Broadcasts are not imported; only the suppression list is.
- **Keep your Resend DNS records while you switch.** Leave the `resend._domainkey` DKIM record and the return-path records on the `send.` subdomain (MX and TXT, or a CNAME) in place; the import report names them for each domain. They use different names from Groundmail's, so mail from both keeps passing while your app moves over. Remove them a few days after the cutover.

The import report has the send-code change for your stack and a prompt for your coding agent. Details: [Import from another provider](https://docs.groundmail.dev/migrations).

---

If you are moving an existing Resend integration, the Groundmail send flow maps closely:

- Bearer API keys
- `POST /emails` with a familiar JSON body
- Webhooks / activity for delivery outcomes

The main migration steps are:

1. swap the base URL
2. swap your API key to `gm_...`
3. verify a sending domain in Groundmail
4. update any provider-specific optional fields

---

## Quick mapping

| Resend | Groundmail |
|--------|---------------|
| `https://api.resend.com` | `https://api.groundmail.dev` |
| `re_...` API key | `gm_...` API key |
| `POST /emails` | `POST /emails` |
| `from` must be verified | `from` must be verified |
| dashboard activity | dashboard activity + deliverability summary |

---

## Minimal curl diff

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

---

## Accepted payload aliases

Groundmail accepts a few migration-friendly aliases on the HTTP send API:

- `htmlBody` or `html_body` -> `html`
- `textBody`, `text_body`, or `plain_body` -> `text`
- `replyTo` -> `reply_to`
- `scheduledAt` -> `scheduled_at`

Attachment aliases are also accepted:

- `filename` -> `name`
- `contentType` -> `content_type`
- `content` -> `data`
- `contentId` -> `content_id`

These aliases are meant to make low-friction migrations easier; new code should still prefer the canonical field names in docs/examples.

---

## Domain verification differences

Unlike provider-managed sandbox products, Groundmail expects you to verify your own sending domain for production traffic.

Before DNS is ready, you can still self-test with the shared sandbox sender:

```json
{
  "from": "noreply@mail.groundmail.dev",
  "to": "you@example.com",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}
```

Sandbox restriction:

- the sandbox `from` domain is only allowed when all recipients match the account email on the API key owner

Once your own domain is verified, switch `from` back to your branded domain.

---

## DNS apply

Groundmail can write DNS for you in two ways:

- Cloudflare: save a token once under **Settings -> Integrations**
- GoDaddy: paste a Personal Access Token on the domain detail page, or pass it through the SDK/CLI locally

See [Domains API](https://docs.groundmail.dev/domains).

---

## SMTP

If your old integration still depends on SMTP, create credentials in the dashboard (**SMTP**) or via `POST /smtp-credentials`, then connect to `smtp.groundmail.dev:587` with username `groundmail`. Same verified domains and plan limits as the HTTP API. Prefer `POST /emails` for new app code. Details: [SMTP relay](https://docs.groundmail.dev/smtp).

---

## Moving from another provider

The importer also brings your suppressions, templates, domains and webhooks over from SendGrid, Postmark, Mailgun, Amazon SES and Azure Communication Services: see [Import from another provider](https://docs.groundmail.dev/migrations). Guides for each:

- [Postmark](https://docs.groundmail.dev/migration/postmark)
- [Amazon SES](https://docs.groundmail.dev/migration/ses)
- [SendGrid](https://docs.groundmail.dev/migration/sendgrid)
- [Mailgun](https://docs.groundmail.dev/migration/mailgun)
- [Azure Communication Services Email](https://docs.groundmail.dev/migration/azure-communication-services) (retiring September 30, 2028)
