From Brevo to Postal, leaving behind what isn't email

Before changing anything, list what your system uses on Brevo. Each item has a place on Postal, or doesn't, and it is better to find that out now.

Under Domains, Postal shows a few records for whoever manages DNS to copy and checks them on its own for up to 72 hours. The domain can stay authenticated on Brevo at the same time: the record names are different.

• Copy the values from your own Brevo screen: the ones in the table are examples from the documentation, and your verification code is unique.
• Because the names are different (mail._domainkey in the Brevo example, postal._domainkey on Postal), both stay valid during the cutover. Check whether any name in your account is the same before publishing.
• Postal notifies you through the domain.updated webhook when the domain becomes verified. See Domains and DNS.

Postal does not accept Brevo's format. The call becomes POST /emails, with the key in Authorization: Bearer instead of the api-key header, and the fields change names. Below, the same email in both formats.

POST https://api.brevo.com/v3/smtp/email
api-key: <Brevo key>
Content-Type: application/json

{
  "sender": { "name": "Aurora Cosméticos", "email": "[email protected]" },
  "to": [{ "email": "[email protected]", "name": "Ana" }],
  "subject": "Your order #10482 is out for delivery",
  "htmlContent": "<p>Order <b>#10482</b> is on its way.</p>",
  "textContent": "Order #10482 is on its way.",
  "tags": ["shipping"]
}

POST https://api.postal.so/emails
Authorization: Bearer ps_your_key
Idempotency-Key: order-10482-shipped
Content-Type: application/json

{
  "from": "Aurora Cosméticos <[email protected]>",
  "to": ["Ana <[email protected]>"],
  "subject": "Your order #10482 is out for delivery",
  "html": "<p>Order <b>#10482</b> is on its way.</p>",
  "text": "Order #10482 is on its way.",
  "tags": [{ "name": "shipping" }]
}

• Without templateId, Brevo requires sender, subject and htmlContent. Postal requires from, subject and html or text.
• Postal adds the Idempotency-Key header: repeating the call with the same key and the same body, within 24 hours, returns the first call's response and does not send again. See Idempotency.
• Postal's documentation does not cover dedicated IPs. If you use the sender.ip field on Brevo, talk to us through the contact form before migrating.
• Prefer an SDK? Postal's (Node.js, PHP and Laravel) use this same API. See SDKs and CLI and the emails reference.

Systems that speak SMTP, such as WordPress, ERPs and store platforms, change four fields: server, port, username and password. On Brevo the password is an SMTP key, not the API key. On Postal it is an API key.

- MAIL_HOST=smtp-relay.brevo.com- MAIL_PORT=587- MAIL_USERNAME=<login SMTP do Brevo>- MAIL_PASSWORD=<chave SMTP do Brevo>+ MAIL_SCHEME=smtps+ MAIL_HOST=smtp.postal.so+ MAIL_PORT=465+ MAIL_USERNAME=postal+ MAIL_PASSWORD=ps_sua_chave

• On Postal, authentication (AUTH PLAIN or AUTH LOGIN) always comes after TLS.
• Postal SMTP has no tags, scheduling or templates: for those, use the API. If your system sends Brevo-specific headers for those features, Postal does not interpret them and they stay as ordinary headers.
• SMTP sends follow the same rules as the API (verified domain, quotas and suppression) and show up in Emails and Logs. See the SMTP guide.

Postal does not convert templates from another platform, but the HTML comes through the Brevo API. The script below lists the active templates, replaces {{params.nome}} with {{{nome}}} and creates each one as a template, with the alias brevo-<id>. It is a starting point: review the result before publishing yours.

const brevoHeaders = { 'api-key': process.env.BREVO_API_KEY }
const postalHeaders = {
  Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  'Content-Type': 'application/json',
}

// Brevo {{params.nome}} becomes {{{nome}}} in Postal
const convert = (text) => text.replace(/\{\{\s*params\.(\w+)\s*\}\}/g, '{{{$1}}}')

const url = 'https://api.brevo.com/v3/smtp/templates?templateStatus=true&limit=100'
const response = await fetch(url, { headers: brevoHeaders })
const { templates } = await response.json()

for (const template of templates) {
  const created = await fetch('https://api.postal.so/templates', {
    method: 'POST',
    headers: postalHeaders,
    body: JSON.stringify({
      name: template.name,
      alias: `brevo-${template.id}`,
      subject: convert(template.subject),
      html: convert(template.htmlContent),
    }),
  })
  if (!created.ok) throw new Error(await created.text())

  const { id } = await created.json()
  await fetch(`https://api.postal.so/templates/${id}/publish`, { method: 'POST', headers: postalHeaders })
}

• Brevo accepts params only in templates written in the “New Template Language”. Older templates need to be reviewed by hand.
• params values that are lists or objects do not carry over: on Postal, each variable is text or a number, and a variable with no value and no default returns 422. Declare optional ones with fallback_value.
• Brevo's response includes each template's sender (sender). On Postal, it comes from from in the send, or from the default sender you store on the template.
• A send always uses the latest published version. See the templates reference; the plan defines how many templates the team has.

The main events exist on both sides, with different names and a different body. On Brevo, the documentation consulted does not describe a signature: it authenticates with a username and password in the URL, a Bearer token, custom headers or an IP list. On Postal, each delivery comes signed with the endpoint's secret.

• Create the endpoint in Webhooks (dashboard or POST /webhooks) and store the signing_secret. Send a test event from the dashboard before switching over.
• Test addresses ([email protected], [email protected] and others) generate real webhooks without using your quota. They depend on the plan.
• Remove the Brevo webhooks only after switching all your traffic: emails that still go out through Brevo keep generating events.

Do this before importing contacts: an address on the suppression list never becomes a contact. Through its API, Brevo lists the contacts blocked or unsubscribed from transactional emails, with the reason for each one.

const reasonsToSuppress = new Set(['hardBounce', 'contactFlaggedAsSpam'])
const emails = []

for (let offset = 0; ; offset += 100) {
  const url = `https://api.brevo.com/v3/smtp/blockedContacts?limit=100&offset=${offset}`
  const response = await fetch(url, { headers: { 'api-key': process.env.BREVO_API_KEY } })
  const { contacts = [] } = await response.json()
  if (contacts.length === 0) break

  for (const contact of contacts) {
    if (reasonsToSuppress.has(contact.reason?.code)) emails.push(contact.email.toLowerCase())
  }
}

for (let i = 0; i < emails.length; i += 100) {
  const response = await fetch('https://api.postal.so/suppressions/batch/add', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ emails: emails.slice(i, i + 100) }),
  })
  if (!response.ok) throw new Error(await response.text())
  await new Promise((resolve) => setTimeout(resolve, 250)) // respeita o limite do plano
}

• The route is GET /v3/smtp/blockedContacts, with up to 100 per page. Each item has email, blockedAt and reason.code. The script brings over only the two delivery reasons and leaves the rest for you to decide.
• In Postal, the addresses come in with the source manual: the difference between a bounce and a complaint isn't kept. The key must have full access. See the suppressions reference.
• Brevo also has a list of blocked domains. Postal's suppression list stores addresses, not whole domains: if you need that, reject the domain in your form or in your system.

Brevo's dashboard exports contacts as CSV, and so does the API. In CRM, Contacts, select the contacts and use More actions, Export, choosing the attributes. Through the API, the request below generates the file and notifies your notifyUrl when it's ready.

POST https://api.brevo.com/v3/contacts/export
api-key: <chave do Brevo>
Content-Type: application/json

{
  "customContactFilter": { "actionForContacts": "subscribed", "listId": 12 },
  "exportAttributes": ["FIRSTNAME", "LASTNAME"],
  "notifyUrl": "https://exemplo.com.br/hooks/brevo-export"
}

• In actionForContacts, the API accepts allContacts, subscribed, unsubscribed and unsubscribedPerList. You must also provide listId, segmentId, modifiedSince or createdSince (a full date, with time zone). Export subscribed and unsubscribed contacts in separate files.
• Without CSV, GET /v3/contacts (up to 1,000 per page) and GET /v3/contacts/lists/{id}/contacts (up to 500) return JSON with attributes, listIds, listUnsubscribed and emailBlacklisted.
• Unsubscribed: in their file, add an Unsubscribed column with sim (yes) on every row and map that column to the Unsubscribed (yes/no) field. Anyone with emailBlacklisted set to true goes here, never in as a subscriber.
• Lists: export one list per file and import each one, choosing the segment. Only static segments receive imported contacts. People who left a single list (listUnsubscribed) need care: if the list became a topic, record those people's opt_out choice with PATCH /contacts/{id}/topics.
• First create the Properties for the attributes you want to keep: the import doesn't create new properties. If you use your own ID (ext_id) and it comes in the file, map it to the external ID field.
• Leave the Trigger automations option off. Contacts that already exist are updated by email, and each file can be up to 20 MB. Your plan's contact limit is on Pricing: 1,000 on Free, 5,000 on Pro and 50,000 on Scale.
• Before sending, run the list through Email validation.

Campaigns and automations don't carry over on their own. We found no export of them to another platform in Brevo's documentation, so treat each one as new and use the chance to review what still makes sense.

• Imports don't start automations unless you turn that option on. Review who would enter before you activate it.
• Each plan has a monthly limit on automation runs.

Switch one flow at a time, with Brevo still on. Start with the test addresses and with yourself, compare deliveries and bounces over the first few days, and only then move the rest.