Migrate from SendGrid to Brew

A cutover, not a sync. Contacts, opt-outs, templates, segments, automations, and API calls move once, then nothing stays connected to SendGrid. The rule behind every step below: only one platform sends live email to a given contact at a time. This guide assumes your Brew brand and sending domain are already set up. If not, verify your domain first. DNS can take up to 72 hours.

Looking to go the other way, designing in Brew and sending from SendGrid? See the SendGrid integration instead.

Not ready to commit? Leave SendGrid sending your transactional mail and route one new marketing email through Brew instead. Steps 1 to 5 cover contacts and a template, which is all you need for a single test send.

Concepts

SendGrid	Brew
Contact (Marketing Campaigns)	Contact
Custom field	Custom property
List	Custom property plus an Audience filter, see Step 4
Segment	Audience
Global unsubscribe	Contact marked `Subscribed: false`, the brand-wide opt-out
Unsubscribe group	A marketing domain’s unsubscribe list, see Step 1
Bounce, invalid email, spam report	Contact marked `Subscribed: false`, see Step 1
Single Send	Email
Automation	Automation
Dynamic template sent with Mail Send	Trigger plus a one-step automation on a transactional-purpose domain, see Step 6
`dynamic_template_data`	The fire’s `payload`, see Step 7
`{{insert first_name "default=there"}}`	`{{ firstName \| there }}`
`{{#each items}}`	`{% for item in trigger.items %}`

Check These Limits First

Brew doesn’t yet match three things SendGrid’s Email API does. If your integration depends on any of them, keep that mail on SendGrid for now and move marketing first.

On SendGrid	In Brew today
High-volume Mail Send calls	Trigger fires share the `automation.runs.write` limit, 60 requests a minute per credential. See Rate Limits
Attachments, such as a PDF invoice	No attachments. Sends and fires carry no files, so link to the file from the email
Event Webhook for delivery, open, and bounce events	Outbound webhooks aren’t available yet. Poll `GET /v1/sends` and `GET /v1/analytics/events` instead. See Events and Webhooks

Every marketing recipient must have opted in to hear from you. Importing or syncing contact data into Brew is not permission to email it. See What You Can Send.

Contacts. Go to Marketing → Contacts. Click the action menu (⋮) next to All Contacts, or next to one list, then click Export. SendGrid emails you when the file is ready. Download it from the Active Exports page within 12 hours of starting the export. Keep these columns:

Email, first name, last name, and any custom fields you use
Any custom field that records how or when someone opted in

Mail you send only through the Email API has no SendGrid contact. Those recipients live in your own user records. Brew creates a contact for each the first time you fire a trigger for them, see Step 7. Suppression. A SendGrid contact has no subscription field. Opt-outs and bad addresses live on the Suppressions lists in the left menu. Export each one:

List	How to export	What to do
Global Unsubscribes	Action menu at the top → Download as CSV	Import, marked `Subscribed: false`
Bounces	Gear icon → Export CSV	Import, marked `Subscribed: false`
Invalid Emails	Gear icon → Download CSV	Import, marked `Subscribed: false`
Spam Reports	Gear icon → Download CSV	Import, marked `Subscribed: false`
Group Unsubscribes	Unsubscribe Groups page, action menu next to a group → Export	See Decide Where Group Opt-Outs Go
Blocks	Gear icon → Export CSV	Don’t import. See below

A block is about your sending IP or your content, not the address. SendGrid doesn’t suppress blocked addresses, so don’t import them as opt-outs. Read the block reasons instead. On SendGrid, a global unsubscribe, bounce, or spam report stops every send to that address, transactional mail included. Brew splits the two:

Subscribed: false stops marketing only. Transactional mail from a transactional-purpose domain still reaches the contact. That’s what you want for a password reset.
Brew can’t import a bounce as a suppression. It suppresses an address after one of its own sends hard-bounces. Fix or remove bounced and invalid addresses in your own user records before you move transactional mail.

Import every opt-out and bad address, even ones that aren’t contacts yet. A contact you leave out can come back later through a form or an integration as a new, subscribed contact. SendGrid keeps engagement history, such as last opened and last clicked, on the contact. Brew’s engagement-based audiences start counting from your import date.

Decide Where Group Opt-Outs Go

Each SendGrid unsubscribe group is one kind of mail, such as a newsletter or product updates. Brew has no groups. Opt-outs work at two levels. Each marketing domain keeps its own unsubscribe list, and Unsubscribe from all covers them all. See Unsubscribes. Map each group before you import:

The group’s mail moves to	Put its opt-outs
Its own Brew marketing domain	That domain’s unsubscribe list
A Brew marketing domain it shares with other groups	That domain’s list. Someone who left one group now leaves them all on that domain
No separate domain	The brand-wide opt-out, as `Subscribed: false`
A transactional-purpose domain	Ask first. Transactional mail ignores opt-outs, so mail people could opt out of probably isn’t transactional

A global unsubscribe always maps to the brand-wide opt-out.

2. Map Your CSV

Column	Required
`Email`	Yes
`First Name`, `Last Name`	Recommended. Map SendGrid’s first and last name columns to them at the mapping step
`Subscribed` (`true`/`false`, defaults `true`)	Add it yourself. Set `false` on every row of the suppression files
Anything else	Becomes a custom property automatically, except columns Brew manages such as `Created At`, which are skipped

Notes:

SendGrid’s export has no consent column. Brew reads opt-outs only from a Subscribed column, so add one to each suppression file before you import it
SendGrid’s activity columns, such as last opened and last clicked, import as plain properties and stop updating on the day you export. Drop the ones you won’t filter on
New columns become camelCase properties. A plan_type column becomes planType. Use that name in merge tags and filters
Empty cells don’t overwrite existing data on update imports
Duplicate rows: the last one wins, so dedupe first
These names belong to built-in contact fields and can’t be used for custom properties: email, firstName, lastName, subscribed, createdAt, updatedAt, validationStatus, lastValidatedAt, importId, csvFileName
Save as UTF-8. Garbled characters at the mapping step usually mean it wasn’t
Dates: day-first dates such as 03/04/2026 (3 April) import correctly when you pick day first at the mapping step, and YYYY-MM-DD needs no choice. See date formats

Full import behavior lives in Add Contacts.

3. Import into Brew

Audience → Add contacts → CSV Upload. Map columns, review, then import. Tick the validation checkbox first if the list hasn’t been checked recently. It costs 2 credits per address, which is worth it before warming up a new domain. Upload the contact file and each suppression file separately. That keeps Subscribed set correctly per batch. Then import each group’s opt-outs into the domain you chose in Step 1. Open Domains in the sidebar, pick the domain, click View list on its Unsubscribes card, then Import CSV. Each file takes up to 10,000 rows. See Import a List from Another Provider. Import contacts before the group files. An address that isn’t a contact yet can end up opted out of all mail, not just one domain. A contact’s Subscribed status says Brew may email them. A consent record says how and when they agreed. Carry both over.

Export the evidence. SendGrid stores no consent record. If you saved an opt-in date or source in a custom field, keep that column as a custom property.
In the app, tick the consent checkbox at the review step. Brew records consent once for the whole file, dated the day you import.
To keep each person’s original opt-in, import over the API instead. POST /v1/contacts takes a consent record per contact, with the original date as capturedAt. It never changes Subscribed.

{
  "contacts": [
    {
      "email": "jane@example.com",
      "consent": { "source": "import", "capturedAt": "2024-03-02T10:15:00Z", "evidence": "SendGrid signup form, optInDate field" }
    }
  ]
}

4. Rebuild Segmentation

Audiences are dynamic filters over contact properties, email engagement, and subscription status. Describe one in plain English or build the filters by hand. SendGrid segments filter on contact fields, email activity, and Single Send or Automation activity. Contact fields carry over as properties. Activity starts fresh in Brew, so a segment like “opened in the last 30 days” refills as you send. Lists don’t have a direct equivalent. Rebuild each list as a custom property plus an Audience filtered on it. Add a column to that list’s export, such as newsletterList set to true, and import it. Keep marketing to people who opted in. A fire for a new address creates a subscribed contact. Once receipts and resets run through Brew, your audience fills with customers who never chose marketing. Build every marketing Audience on a property only opted-in contacts carry, such as marketingOptIn: true from your import. Before cutover, spot-check that a recreated Audience’s membership count is in the right ballpark against the original segment. A wrong translation can undercount or overcount who gets an email, and that isn’t always visible in the UI.

5. Rebuild Templates and Merge Tags

You have	Use	Result
A template’s HTML	Import email (the `</>` button)	Editable email, imports the original markup as-is
A Figma frame	Connect with Figma	Responsive email
A screenshot	Upload image to recreate	Rebuilt structure and styling
A live email	Forward to `hello@email.brew.new`	Lands in Templates → Forwarded

To get a dynamic template’s HTML, open Email API → Dynamic Templates in SendGrid, then the template’s active version. In the Design Editor, the Build tab’s Advanced section exports the HTML. In the Code Editor, copy it. From code, GET /v3/templates/{template_id} returns each version’s html_content. In Brew, open Emails in the sidebar, then use the import tools in the toolbar right of the canvas. See Importing existing designs. For most templates, use the HTML or screenshot as reference. Prompt Brew to rebuild it against your brand rather than treating the import as finished. It’s faster, and the result inherits your brand identity automatically. Running a long parallel test instead of a fast cutover? You can design in Brew and still send from SendGrid. Click Send in the top right, choose Export template, and pick SendGrid. That pushes the finished email to SendGrid as a dynamic template through the SendGrid integration.

Translate Merge Tags

SendGrid dynamic templates use Handlebars. Brew runs Liquid. Both use {{ }} for values, but logic blocks look different. Brew property names are camelCase and case-sensitive, and a snake_case name renders empty. If you keep an imported template’s HTML as it is, replace SendGrid’s tags before you send:

{{first_name}} becomes {{ firstName }}, and {{last_name}} becomes {{ lastName }}. A custom field becomes the camelCase name from your import, such as {{ planType }}.
{{insert first_name "default=there"}} becomes {{ firstName | there }}. The fallback after the pipe shows for contacts with nothing on file.
Values from dynamic_template_data become {{ trigger.* }}, named after the key you send in the fire’s payload. {{order.number}} becomes {{ trigger.order.number }}. See Step 7.
{{#if}}, {{else if}}, {{else}}, and {{/if}} become {% if %}, {% elsif %}, {% else %}, and {% endif %}. {{#unless}} becomes {% unless %}.
Comparison helpers become operators inside {% if %}. {{#equals a b}} is {% if a == b %}, and notEquals, greaterThan, and lessThan are !=, >, and <. {{#and}} and {{#or}} become and and or.
{{#each order.items}}{{this.name}}{{/each}} becomes {% for item in trigger.order.items %}{{ item.name }}{% endfor %}. Inside the loop, write the full path where Handlebars used @root.
{{formatDate}} and {{length}} become Liquid filters, such as date and size. Check each one against the Liquid templating reference.
Triple braces, such as {{{name}}}, are a legacy spelling in Brew. Rewrite them with two braces.
Legacy substitution tags, such as -name- sent in substitutions, become {{ trigger.name }} from the fire’s payload.
Delete {{{unsubscribe}}}, {{{unsubscribe_preferences}}}, the <%asm_...%> tags, and the {{Sender_Address}} family. Brew adds the unsubscribe link and your mailing address to every marketing email. Transactional mail carries no unsubscribe link.
Remove {{Weblink}}, the view-in-browser link.

6. Rebuild Automations

Marketing Campaigns automations become Brew automations on a marketing-purpose domain.

SendGrid Automation	Brew
Entry criteria: a list, such as a welcome series	Custom HTTP trigger fired from your signup form, or an integration event
Entry criteria: a segment	Manual-audience run, or a trigger you fire when the contact qualifies
Time between emails	Wait
Exit criteria	Filter before each Send Email step
Unsubscribe group	The sending domain on the Send Email step
Email	Send Email, pointed at your rebuilt template

Transactional email. Most SendGrid mail is a Mail Send call with a dynamic template, like a receipt. In Brew, the sending domain decides what’s transactional. Rebuild each template as a trigger plus a one-step automation on a transactional-purpose domain. One trigger per kind of email. See Transactional Email. Test-fire before publishing. Leave every rebuilt automation unpublished until cutover day, which is what prevents a double-send. Build an Automation covers the trigger setup and the test step.

7. Swap the API Calls in Your Code

SendGrid’s v3 API lives at https://api.sendgrid.com/v3 and takes a bearer key. Brew does too, at https://brew.new/api/v1. Contact upsert. Before, with SendGrid:

await fetch('https://api.sendgrid.com/v3/marketing/contacts', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRID_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    list_ids: [process.env.SENDGRID_NEWSLETTER_LIST_ID],
    contacts: [
      {
        email: "user@example.com",
        first_name: "Ada",
        last_name: "Lovelace",
        custom_fields: { [process.env.SENDGRID_PLAN_FIELD_ID]: "pro" },
      },
    ],
  }),
});

After, with Brew:

await fetch('https://brew.new/api/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BREW_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: "user@example.com",
    firstName: "Ada",
    lastName: "Lovelace",
    subscribed: true,
    customFields: { plan: "pro", newsletterList: true },
    consent: { source: "form", capturedAt: new Date().toISOString() },
  }),
});

SendGrid keys custom fields by field ID and queues the upsert, answering 202 with a job_id. Brew takes custom fields by name. A list becomes a custom property, as in Step 4. Adding someone to a SendGrid list opts no one in. In Brew, subscribed: true opts the person in, and the consent record says how. The consent record never changes subscribed. subscribed: true applies only to a new contact. A single upsert that asks for it on an opted-out contact gets 422 RESUBSCRIBE_NOT_ALLOWED, and nothing is written. Handle that 422 by sending the same call without subscribed. Transactional sends. A Mail Send call becomes a fire. Fire the trigger, and its published automation sends the email. Before, with SendGrid:

await fetch('https://api.sendgrid.com/v3/mail/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRID_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: { email: "orders@example.com" },
    template_id: process.env.SENDGRID_RECEIPT_TEMPLATE_ID,
    personalizations: [
      {
        to: [{ email: "user@example.com" }],
        dynamic_template_data: {
          first_name: "Ada",
          order: { number: "1042", items: [{ name: "Mug", qty: 2 }] },
        },
      },
    ],
  }),
});

After, with Brew:

await fetch(
  `https://brew.new/api/v1/automations/triggers/${process.env.BREW_ORDER_PLACED_TRIGGER_ID}/fire`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.BREW_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `order-placed-${order.id}`,
    },
    body: JSON.stringify({
      payload: {
        email: "user@example.com",
        firstName: "Ada",
        order: { number: "1042", items: [{ name: "Mug", qty: 2 }] },
      },
    }),
  },
);

The to address becomes the payload’s email, the contact the automation runs for. dynamic_template_data becomes the payload, read in the email as {{ trigger.order.number }}. The template, sender, and subject move into the automation, so template_id, from, and asm leave your code. Nest order data in an object, as above. Object and array fields stay template data. Declared top-level values, such as firstName, are saved on the contact. Fire once per recipient. A Mail Send call with several personalizations becomes several fires, each with its own key. Each fire counts toward the rate limit in Check These Limits First. SendGrid’s Mail Send takes no idempotency key, so a retry can send twice. On Brew, send an Idempotency-Key derived from the action, like the order id above. A repeat with the same key starts nothing new. See Idempotency. A fire answers 202 once its runs start, not when the email is delivered. A suppressed address counts under counts.skipped. 422 NO_PUBLISHED_AUTOMATION means nothing published listens for the trigger, so publish before you point code at it. Full request shapes are in the API reference. This section shows the shape of the migration, not a copy-paste replacement for your code.

8. Cut Over

Move in this order:

Rebuild while SendGrid keeps sending. Import contacts and rebuild segments, templates, and automations. None of it touches live sending. Keep every Brew automation unpublished.
Check your segments. Confirm each recreated Audience’s membership count against the original. See Step 4.
Refresh opt-outs. Right before your first Brew send, export SendGrid’s new global unsubscribes, bounces, invalid emails, and spam reports and import them into Brew as Subscribed: false. Export the group unsubscribes again too. Repeat before each type you move, until SendGrid stops sending. Anyone who opted out during the rebuild stays opted out.
Warm up with the first type you move. Pause that type on SendGrid first, so nobody gets it from both. Send to your most engaged contacts first and ramp over several days. Gradual send does the ramping for you. No history means no reputation, even on a verified domain.
Move one type at a time. Single Sends first, then automations. For each automation, in order: disable it on SendGrid, publish the Brew automation, then point its signup forms or app events at Brew. Watch each in analytics before you move the next.
Move transactional email last, and only mail the limits in Check These Limits First don’t block. Before you move any, add a separate transactional-purpose subdomain (see Transactional Email). A fire for a new address creates a subscribed contact, so only send marketing to people who opted in. Order confirmations and resets are the highest-stakes sends. Cut them over one at a time, and test-run each automation with a real payload before you point production code at its trigger.
Keep SendGrid as a fallback. Leave its API key and templates in place for a couple of weeks, so you can switch a code path back. Then downgrade or cancel.

Never leave the same email type live in both places at once. That’s how a contact gets the same receipt twice.

Quick Reference

Task	Where in Brew
Import contacts	Audience → Add contacts → CSV Upload
Import a group’s opt-outs	Domains → pick the domain → Unsubscribes → View list → Import CSV
Manage unsubscribes and bounces	Audience tab, contact detail view
Build a segment	Audience → Create Audience
Import a template	Emails → canvas → Import
Build a flow	Automations in the sidebar
Send a transactional email	`POST /v1/automations/triggers/{triggerEventId}/fire`
API keys	Settings → API

Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Self-Service Tools
Talk to Our Team

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.

Brew University

Recipes

Migrate to Brew

Migrate from SendGrid to Brew

Concepts

Check These Limits First

Decide Where Group Opt-Outs Go

2. Map Your CSV

3. Import into Brew

4. Rebuild Segmentation

5. Rebuild Templates and Merge Tags

Translate Merge Tags

6. Rebuild Automations

7. Swap the API Calls in Your Code

8. Cut Over

Quick Reference

Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Concepts

​Check These Limits First

​1. Export Contacts, Consent, and Suppression

​Decide Where Group Opt-Outs Go

​2. Map Your CSV

​3. Import into Brew

​Bring Your Consent Records

​4. Rebuild Segmentation

​5. Rebuild Templates and Merge Tags

​Translate Merge Tags

​6. Rebuild Automations

​7. Swap the API Calls in Your Code

​8. Cut Over

​Quick Reference

​Need Help?

Search Documentation

Ask ChatGPT or Claude

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Concepts

Check These Limits First

1. Export Contacts, Consent, and Suppression

Decide Where Group Opt-Outs Go

2. Map Your CSV

3. Import into Brew

Bring Your Consent Records

4. Rebuild Segmentation

5. Rebuild Templates and Merge Tags

Translate Merge Tags

6. Rebuild Automations

7. Swap the API Calls in Your Code

8. Cut Over

Quick Reference

Need Help?