To keep this concrete without exposing anyone's code, this article works through a simulated codebase: a nine-year-old Rails monolith whose email system grew on SendGrid, one team after another. It is a composite I made up, not a real migration, and every count below belongs to the simulation. The SendGrid and Brevo details come from their documentation, cited as I go and listed at the end.
The simulated app
In this simulated app there are 38 mailers. Most use Action Mailer over SMTP. Ten newer ones call the v3 Mail Send API through sendgrid-ruby. The SMTP half is not invented: one of my own Rails projects sends through SendGrid's relay with apikey as the user name.
The oldest mailers set an X-SMTPAPI header for categories, unique arguments, substitutions and a legacy template. There are 14 legacy templates and 61 dynamic ones. Template ids sit in mailers, in two jobs and in a notification_types table.
The Event Webhook writes an email_events table. A bounce flips a flag on users. Support reads the table, and a nightly job re-sends failed invoices. Categories feed a reporting page. One unsubscribe group and one IP pool exist for invoices. Inbound Parse on a reply. subdomain feeds ticket replies. Sidekiq holds reminders enqueued days ahead. The API key lives in Rails credentials, in a worker's systemd unit and in a CI variable, and nobody knows who owns the templates.
Discovery
Search the code first, then the database, then the SendGrid dashboard.
grep -rnE "sendgrid|SENDGRID" app lib config Gemfile* .env*
grep -rniE "x-smtpapi|smtpapi|unique_args|custom_args|categories|asm|ip_pool" app lib
grep -rnE "d-[0-9a-f]{20,}" app lib config db
grep -rnE "api\.sendgrid\.com|smtp\.sendgrid\.net" . --include="*.rb" --include="*.yml"
Dump any table or serialized Sidekiq payload that can hold a template id. Then list the dashboard: API keys, legacy and dynamic templates, the Event Webhook, Inbound Parse, unsubscribe groups, IP pools, and the DNS records for each sending domain.
Write down who reads each result. In the simulation, five things consume event data. Only two of them are in the app's code.
What maps to what, and what does not
| SendGrid | Brevo |
|---|---|
SMTP relay, user apikey1 | smtp-relay.brevo.com:5872, the SMTP login shown in the dashboard and an SMTP key, not an API key3 |
v3 Mail Send4, sendgrid-ruby5 | POST /v3/smtp/email with an api-key header6, brevo gem7 |
Dynamic template d-…, dynamic_template_data8 | Integer templateId, params6 |
Legacy template selected through X-SMTPAPI9 | Gap: no documented equivalent over SMTP. Convert it and send through the API |
categories4 | tags6 |
custom_args, unique_args10 | One X-Mailin-custom header, echoed in webhook events11; also store the returned messageId |
| Unsubscribe groups | Gap: none found for transactional sends |
ip_pool_name4 | sender.ip header, dedicated-IP accounts only12 |
send_at, capped at 72 hours ahead4 | scheduledAt12 |
| Event Webhook13 | Transactional webhooks11 |
| Suppressions14 | Blocked or unsubscribed contacts15 |
| Inbound Parse16 | Inbound parsing webhook17 |
The gaps decide scope. Each one is a feature the app uses and Brevo's documentation does not offer. The X-SMTPAPI header is documented with sub, category, unique_args, filters, send_at, asm_group_id and ip_pool18. Dynamic templates are not supported through it9, which is why the app has two generations of sending code.
One seam before any switch
Do not touch a provider yet. Put one boundary in the app that every template-based send goes through, and one file that maps logical template names to provider ids.
# config/mail_templates.yml
invoice_reminder:
provider: sendgrid
sendgrid: "d-REPLACE_ME"
brevo: 31
class MailGateway
def self.deliver(template:, to:, data:, tags: [])
entry = Rails.application.config_for(:mail_templates).fetch(template)
adapter = entry[:provider] == "brevo" ? BrevoAdapter : SendgridAdapter
adapter.deliver(entry.fetch(entry[:provider].to_sym), to, data, tags)
end
end
class SendgridAdapter
def self.deliver(template_id, to, data, tags)
body = {
from: { email: ENV.fetch("MAIL_FROM") },
template_id: template_id,
categories: tags,
personalizations: [{ to: [{ email: to }], dynamic_template_data: data }]
}
sg = SendGrid::API.new(api_key: ENV.fetch("SENDGRID_API_KEY"))
response = sg.client.mail._("send").post(request_body: body)
raise "SendGrid #{response.status_code}" unless response.status_code.start_with?("2")
end
end
The from, template_id, categories and personalizations[].dynamic_template_data fields are from the Mail Send reference4. The client call follows the sendgrid-ruby README5.
Two details matter in this app. First, the provider and the id are read at send time, not stored in the job. Reminders enqueued days ago would otherwise carry a SendGrid id into a Brevo world. Second, the 72-hour cap4 means the app's own queue holds far-future mail, which makes the switch easier: the provider call happens late.
Ship the seam alone, with the provider still sendgrid for everything. Move the hard-coded ids from mailers, jobs and the notification_types table into the YAML. Mail that renders Action Mailer views keeps its SMTP path for now.
Converting templates
A legacy template uses substitution tags and <%subject%> and <%body%>9. A dynamic one uses Handlebars19. Brevo's template language20 is the target for both.
A dynamic template with a variable, a conditional and a loop:
Hello {{ name }},
{{#if overdue}}Your invoice is overdue.{{/if}}
{{#each lines}}
{{this.label}} - {{this.amount}}
{{/each}}
The Brevo version, with the data under params:
Hello {{ params.name }},
{% if params.overdue %}Your invoice is overdue.{% endif %}
{% for line in params.lines %}
{{ line.label }} - {{ line.amount }}
{% endfor %}
Helpers like equals, formatDate and insert19 need a hand-checked replacement. Brevo documents filters such as upper, floatformat:2, date, and default:"there", which covers insert with a fallback21. Silent differences to test for:
- SendGrid's
equalscoerces types (3equals"3"), and its editor preview does not render those comparisons correctly19. - Brevo's if-statement help says to avoid floats in conditions and pass them as strings22.
- A missing nested key renders as empty text in a documented SendGrid example19. I found no stated rule for Brevo.
- SendGrid's triple braces switch off HTML escaping19. Brevo escapes all variables by default and uses the
safefilter instead21.
Brevo only applies params to templates in the new template language, per the SDK model12. You can create templates with POST /v3/smtp/templates23 and update them with PUT /v3/smtp/templates/{templateId}24, so the templates can live in the repository.
The Brevo adapter is the same shape as the SendGrid one.
class BrevoAdapter
ENDPOINT = URI("https://api.brevo.com/v3/smtp/email")
def self.deliver(template_id, to, data, tags)
request = Net::HTTP::Post.new(ENDPOINT, "api-key" => ENV.fetch("BREVO_API_KEY"),
"content-type" => "application/json")
request.body = { templateId: template_id, to: [{ email: to }], params: data, tags: tags }.to_json
response = Net::HTTP.start(ENDPOINT.host, ENDPOINT.port, use_ssl: true) { |h| h.request(request) }
raise "Brevo #{response.code}: #{response.body}" unless response.code == "201"
JSON.parse(response.body).fetch("messageId")
end
end
The send documentation gives a 201 and a messageId6. Action Mailer views play no part here, because Brevo renders the template. Send each converted template to a test inbox with real-shaped data, including the empty list, and compare it with the SendGrid email. Brevo has a send-to-test-list endpoint25.
Side by side, one mail type at a time
Set up Brevo before sending anything. The sender must be registered and verified6, and the domain authenticated. Brevo's domain page shows a Brevo code record, a DKIM record and a DMARC record26. Add the code and DKIM records next to the SendGrid ones and delete nothing. A domain can only publish one DMARC record, so keep the existing one rather than adding a second.
Then flip provider for one low-risk type, such as an internal notification, and watch it. Move the rest in groups. Invoices and password resets go last, because the nightly re-send job and support both depend on them.
For the Action Mailer mailers, SMTP settings can be overridden per message with delivery_method_options27. Pass the full Brevo hash from one mailer and leave the global SendGrid settings alone. Convert the legacy mailers to the gateway when you touch their templates.
Events, status table and in-flight mail
Add Brevo's webhook before the first live Brevo send: POST /v3/webhooks with type set to transactional, and authentication by IP allowlist, URL credentials or bearer token28. Keep the SendGrid endpoint. SendGrid retries failed event posts for up to 24 hours13, so messages sent just before a switch still report back.
Add provider and provider_message_id columns to email_events, and map Brevo's names onto the existing ones:
BREVO_TO_STATUS = {
"request" => "processed",
"delivered" => "delivered",
"deferred" => "deferred",
"hard_bounce" => "bounce",
"soft_bounce" => "bounce",
"spam" => "spamreport",
"unsubscribed" => "unsubscribe",
"unique_opened" => "open",
"click" => "click"
}.freeze
Event names come from Brevo's11 and SendGrid's10 references. Three points need a decision, not a lookup. SendGrid's dropped has no documented one-to-one; read the payloads for blocked, invalid_email and error. Brevo's soft_bounce should probably not flip the user flag. SendGrid's group events have no counterpart I found. Correlate on message-id from Brevo's payload and the messageId you stored at send time, or on the X-Mailin-custom value if you set one11. Brevo's payload does not carry sg_message_id, and SendGrid's sg_event_id, which the event reference recommends for deduplication10, needs your own substitute.
Suppressions
SendGrid keeps suppressing bounces, invalid emails, spam reports and unsubscribes, but not blocks14. Export those from SendGrid, and get them onto Brevo's blocklist before the first send to a real user. The API reference documents reading blocked contacts and unblocking them15. I found no documented bulk import in the pages I read, so confirm that route in Brevo's help centre. Until that is settled, have the gateway check users.email_valid before every send, so the app itself refuses to mail an address that bounced.
Inbound Parse
SendGrid's Inbound Parse takes an MX record on a dedicated hostname and posts multipart form data16. Brevo's equivalent posts parsed JSON with an items array, from a webhook of type inbound and event inboundEmailProcessed, on a receiving domain that differs from the sending domain17. The controller that handles ticket replies needs rewriting, not remapping. I would move it last.
Watching, rolling back, what stays ugly
After each step, check the Brevo logs against stored messageIds, the event table filling, the DKIM and DMARC results in a received message's raw headers, and the bounce flag changing as before.
Rollback is a YAML change per mail type, then a deploy. It works only while the SendGrid key, domain records and webhook route are alive. Messages Brevo has already accepted are not recalled.
Some of it will stay ugly. The unsubscribe group has no equivalent, several custom_args squeeze into one header, and a few legacy mailers will keep their SMTP path.
Checklist
- Grep results and dashboard inventory written down, with a reader for each event.
- Gaps decided: unsubscribe groups, custom args, IP pool, legacy templates.
- Seam in place and template ids in one file, resolved at send time.
- Each template converted and tested with real-shaped data.
- Sender verified, DNS records added beside the old ones.
- Brevo webhook live, events mapped onto the same status table.
- Suppressions carried over before real sends.
- One mail type at a time; Inbound Parse last.
- SendGrid kept alive until its events stop arriving.
References
-
Twilio SendGrid, "How to send an Email with SMTP," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Connect Brevo SMTP to Supabase: send your auth emails," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/supabase-smtp-integration. Accessed: 19 Nov. 2026. ↩
-
Brevo, "SMTP relay integration," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/smtp-integration. Accessed: 19 Nov. 2026. ↩
-
Twilio SendGrid, "Mail Send," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3 ↩4 ↩5 ↩6
-
Twilio SendGrid, "sendgrid-ruby," GitHub repository. [Online]. Available: https://github.com/sendgrid/sendgrid-ruby. Accessed: 19 Nov. 2026. ↩ ↩2
-
Brevo, "Send a transactional email," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/send-a-transactional-email. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3 ↩4 ↩5
-
Brevo, "brevo-ruby," GitHub repository. [Online]. Available: https://github.com/getbrevo/brevo-ruby. Accessed: 19 Nov. 2026. ↩
-
Twilio SendGrid, "Send an email with dynamic templates," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/ui/sending-email/how-to-send-an-email-with-dynamic-templates. Accessed: 19 Nov. 2026. ↩
-
Twilio SendGrid, "Sending a Legacy Transactional Template Email over SMTP," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/sending-email/how-to-use-a-transactional-template-with-smtp-or-v2. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3
-
Twilio SendGrid, "Event Webhook Reference," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3
-
Brevo, "Transactional webhooks," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/transactional-webhooks. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3 ↩4
-
Brevo, "Brevo::SendSmtpEmail," brevo-ruby documentation, GitHub. [Online]. Available: https://github.com/getbrevo/brevo-ruby/blob/main/docs/SendSmtpEmail.md. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3
-
Twilio SendGrid, "Getting started with the Event Webhook," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook. Accessed: 19 Nov. 2026. ↩ ↩2
-
Twilio SendGrid, "Suppressions," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/ui/sending-email/index-suppressions. Accessed: 19 Nov. 2026. ↩ ↩2
-
Brevo, "Get the list of blocked or unsubscribed transactional contacts," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/reference/get-transac-blocked-contacts. Accessed: 19 Nov. 2026. ↩ ↩2
-
Twilio SendGrid, "Configure the inbound parse webhook," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/parsing-email/setting-up-the-inbound-parse-webhook. Accessed: 19 Nov. 2026. ↩ ↩2
-
Brevo, "Parse inbound email," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/inbound-parse-webhooks. Accessed: 19 Nov. 2026. ↩ ↩2
-
Twilio SendGrid, "Building an X-SMTPAPI Header," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/sending-email/building-an-x-smtpapi-header. Accessed: 19 Nov. 2026. ↩
-
Twilio SendGrid, "Using Handlebars," SendGrid Docs. [Online]. Available: https://www.twilio.com/docs/sendgrid/for-developers/sending-email/using-handlebars. Accessed: 19 Nov. 2026. ↩ ↩2 ↩3 ↩4 ↩5
-
Brevo, "[Manual] Personalize your messages with dynamic content (Brevo Template Language)," Brevo Help Center. [Online]. Available: https://help.brevo.com/hc/en-us/articles/4402386448530. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Modify the output of a variable using filters," Brevo Help Center. [Online]. Available: https://help.brevo.com/hc/en-us/articles/4405381108626. Accessed: 19 Nov. 2026. ↩ ↩2
-
Brevo, "[Manual] Show or hide content using if statements," Brevo Help Center. [Online]. Available: https://help.brevo.com/hc/en-us/articles/360001030599. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Create an email template," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/reference/create-smtp-template. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Update an email template," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/reference/update-smtp-template. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Send a template to your test list," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/reference/send-test-template. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Domain authentication and validation," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/domain-authentication-and-verification. Accessed: 19 Nov. 2026. ↩
-
Ruby on Rails, "Action Mailer Basics," Ruby on Rails Guides. [Online]. Available: https://guides.rubyonrails.org/action_mailer_basics.html. Accessed: 19 Nov. 2026. ↩
-
Brevo, "Secure webhook calls," Brevo API Documentation. [Online]. Available: https://developers.brevo.com/docs/secured-webhooks. Accessed: 19 Nov. 2026. ↩