Sending a transactional email is only half the job. You also want to know when it bounced, got blocked, or was marked as spam, so you can stop emailing that address and protect your sender reputation. Polling an API for that is wasteful. Brevo (formerly Sendinblue) can push each event to your server as it happens, using a webhook.

In this post we'll build a small Flask receiver, protect it with a bearer token, register it with the Brevo API, and act on the events that matter.

What Brevo sends

For transactional email, Brevo POSTs a JSON body to your URL for each event you subscribe to. The fields you'll use most:

Note the hyphen in message-id and the underscores in event names like hard_bounce. They don't match the camelCase names (hardBounce) you use when creating the webhook, which trips a lot of people up.

1. The receiver

pip install flask requests

# app.py
import hmac
import os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_TOKEN = os.environ["BREVO_WEBHOOK_TOKEN"]  # a long random string you choose

SUPPRESS = {"hard_bounce", "invalid_email", "blocked", "spam", "unsubscribed"}


def authorized(req) -> bool:
    header = req.headers.get("Authorization", "")
    expected = f"Bearer {WEBHOOK_TOKEN}"
    return hmac.compare_digest(header, expected)


def handle_event(evt: dict) -> None:
    kind = evt.get("event")
    email = evt.get("email")
    msg_id = evt.get("message-id")

    if kind in SUPPRESS:
        # Stop emailing this address. Replace with your own DB call.
        print(f"suppress {email}: {kind} ({evt.get('reason', '')})")
    elif kind == "soft_bounce":
        # Temporary problem (full inbox, server down). Count it, don't suppress yet.
        print(f"soft bounce for {email}: {evt.get('reason', '')}")
    elif kind == "delivered":
        print(f"delivered {msg_id} to {email}")
    else:
        print(f"{kind} for {email}")


@app.post("/webhooks/brevo")
def brevo_webhook():
    if not authorized(request):
        abort(401)

    payload = request.get_json(silent=True)
    if payload is None:
        abort(400)

    # One event per request normally; a list if you enable batching
    events = payload if isinstance(payload, list) else [payload]
    for evt in events:
        handle_event(evt)

    return "", 200

A few design choices here:

• Answer fast. The route does a little work and returns 200. If your real handling is slow (database writes, CRM updates), push events onto a queue and process them in the background.
• Constant-time compare. hmac.compare_digest avoids leaking the token through timing differences.
• Handle both shapes. Brevo can batch events (more on that below), so the code accepts a single object or a list.
• Be idempotent. Treat the same event arriving twice as harmless, e.g. suppressing an address that's already suppressed does nothing.

Run it locally:

export BREVO_WEBHOOK_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
flask --app app run --port 5000

Brevo needs a public HTTPS URL, so for testing expose the port with a tunnel tool of your choice and note the URL it gives you.

2. Test it before Brevo does

Fake an event with curl to check your auth and parsing:

curl -i -X POST http://localhost:5000/webhooks/brevo \
  -H "Authorization: Bearer $BREVO_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"hard_bounce","email":"bad@example.com","message-id":"<test@local>","reason":"mailbox does not exist","ts_event":1767225600}'

You should see 200 and a "suppress" line in the Flask log. Try it without the header and you should get 401.

3. Register the webhook with the API

You can create webhooks in the Brevo dashboard, but doing it in code keeps it reproducible across environments. The endpoint is POST https://api.brevo.com/v3/webhooks:

# create_webhook.py
import os
import requests

resp = requests.post(
    "https://api.brevo.com/v3/webhooks",
    headers={
        "api-key": os.environ["BREVO_API_KEY"],
        "accept": "application/json",
        "content-type": "application/json",
    },
    json={
        "url": "https://your-public-url.example.com/webhooks/brevo",
        "description": "Bounces and complaints -> suppression list",
        "type": "transactional",
        "events": [
            "delivered", "hardBounce", "softBounce", "blocked",
            "spam", "invalid", "unsubscribed",
        ],
        "auth": {"type": "bearer", "token": os.environ["BREVO_WEBHOOK_TOKEN"]},
    },
    timeout=15,
)
print(resp.status_code, resp.json())  # 201 {"id": 1234567}

A 201 with an id means it's live. Save that ID so you can update or delete the webhook later. Only subscribe to the events you'll act on: adding opened and click on a busy account means a lot of extra traffic.

4. Securing it properly

The bearer token above is one of several options Brevo supports. You can also:

• put basic-auth credentials in the URL (https://user:pass@host/path),
• send custom headers with each call (the headers field on the create request), or
• allowlist Brevo's published IP ranges at your firewall.

Pick at least one. An open webhook URL lets anyone mark your customers as bounced.

5. High volume? Turn on batching

Add "batched": true when creating the webhook and Brevo groups events into windows of about five minutes, with up to 500 events per call. You'll get far fewer requests, at the cost of a short delay. That's why the receiver already loops over a list.

6. Use the custom header to link events to your data

When you send an email through the API, add a header such as "X-Mailin-custom": "user:42|order:A-1042". Brevo returns that value in the webhook's X-Mailin-custom field, so you can update the right record without looking up the message ID.

Wrapping up

With about 60 lines of Python, hard bounces and spam complaints stop silently piling up. Your list stays clean and your sender reputation stays healthy. Field names and event lists can change, so keep Brevo's developer docs open when you extend this.

The full guide, with dashboard setup steps and a testing walkthrough, is here: Brevo Webhooks: Simple Setup Guide.

Password resets, order receipts and contact-form alerts are the emails users notice most when they go missing. Sending them straight from your server often lands them in spam. Routing them through an SMTP relay, a server built only for sending mail, usually fixes that.

Brevo (formerly Sendinblue) includes SMTP on every plan, including the free one, which Brevo's pricing page lists at up to 300 emails a day. Here's a minimal Python setup using only the standard library.

The settings you need

From Settings > SMTP & API > SMTP in Brevo:

Store the login and key as environment variables, never in code:

export BREVO_SMTP_LOGIN="your-smtp-login"
export BREVO_SMTP_KEY="your-smtp-key"
export MAIL_FROM="Your App <hello@yourdomain.com>"

Sending with smtplib

import os
import smtplib
from email.message import EmailMessage

def send_email(to: str, subject: str, text: str, html: str | None = None) -> None:
    msg = EmailMessage()
    msg["From"] = os.environ["MAIL_FROM"]
    msg["To"] = to
    msg["Subject"] = subject
    msg.set_content(text)
    if html:
        msg.add_alternative(html, subtype="html")

    with smtplib.SMTP("smtp-relay.brevo.com", 587, timeout=20) as server:
        server.starttls()
        server.login(os.environ["BREVO_SMTP_LOGIN"], os.environ["BREVO_SMTP_KEY"])
        server.send_message(msg)

if __name__ == "__main__":
    send_email(
        "you@example.com",
        "Reset your password",
        "Use this link to reset your password: https://example.com/reset/123",
        '<p>Use this link to reset your password:</p><p><a href="https://example.com/reset/123">Reset password</a></p>',
    )

On port 465, swap smtplib.SMTP(...) plus starttls() for smtplib.SMTP_SSL("smtp-relay.brevo.com", 465).

When login fails (535 Authentication failed)

• The username is the SMTP login from the SMTP page, not smtp-relay.brevo.com.
• The password must be an SMTP key. Your account password and API keys won't work here.
• Re-paste the key if a space or line break slipped in.
• Don't mix SSL with port 587 or STARTTLS with 465.
• Brevo switches off keys that haven't sent a good email in 90 days, so an old key may simply be disabled. Generate a new one.

Before production

Authenticate your sending domain in Brevo (SPF, DKIM and DMARC), send from an address on that domain, and check Transactional > Logs after your first test to confirm delivery.

The full walkthrough, including how to generate the SMTP key and choose a port, is on Omni Genz: What is an SMTP relay? Brevo SMTP relay setup guide.