Brevo API: praktický průvodce pro vývojáře

Import kontaktu může vrátit 201 a přesto být chybný: ztratilo se ID zdroje, zvolil se špatný seznam nebo se ignorovalo dřívější odhlášení. Jde o rozhodnutí o datech, ne o detaily HTTP.

Průvodce nejprve ukáže funkční požadavek Brevo a potom kontroly pro malou opakovatelnou synchronizaci.

Co Brevo API pokrývá

Vše žije pod jedním hostitelem a jednou cestou s verzí. Dokumentace pro vývojáře dělí toto rozhraní do čtyř produktových oblastí:

• Zasílání zpráv: transakční e-maily, SMS a WhatsApp včetně dávkových odeslání, plánování a aktivity zpráv.
• Marketingová platforma: kontakty, seznamy, segmenty a e-mailové kampaně.
• eCommerce: produkty, objednávky a sledování událostí zákazníků.
• Konverzace: chatovací widget a programové řízení konverzací.

Tyto oblasti sdílejí jeden účet, jednu databázi kontaktů a jeden API klíč. To je pohodlné a občas i nebezpečné: skript napsaný proti představě o testovacích datech mluví se stejnými kontakty, kterým odesíláte kampaně.

Transakční versus marketingové

Obě rodiny se chovají natolik odlišně, že jejich záměna je nejčastější chybou v návrhu.

Pokud teprve zvažujete, zda je Brevo vůbec ta správná platforma, tuto oblast pokrývá přehled platformy.

Autentizace a správa klíčů

Brevo používá prostý API klíč ve vlastní hlavičce. Hlavička se jmenuje api-key, nikoli Authorization, a nemá prefix Bearer. Na tom klopýtne téměř každý, kdo předtím pracoval s jiným API pro zasílání zpráv.

OAuth může u podporovaných operací použít token Bearer; běžný API klíč stále patří do hlavičky api-key.

curl https://api.brevo.com/v3/account \
  -H "api-key: $BREVO_API_KEY"

Klíče se generují v aplikaci Brevo v nastavení účtu, v sekci SMTP and API, na záložce API keys. Každému klíči dejte výstižný název navázaný na systém, který jej používá. Hodnota klíče se zobrazí přesně jednou při generování, takže pokud ji ztratíte, vygenerujete nový klíč místo obnovení starého.

Několik praktických pravidel:

• Vydávejte samostatný klíč pro každé prostředí a každou službu. Zneplatnění kompromitovaného klíče by nikdy nemělo položit tři nesouvisející systémy.
• Standardní API klíče platí pro celý účet. Ke každému klíči přistupujte jako k plnému přístupu ke kontaktům, odesílání i CRM datům.
• Brevo podporuje také OAuth 2.0 pro aplikace, které jednají jménem jiných účtů Brevo. Popis najdete vedle postupu s klíči v dokumentu authentication schemes.
• MCP server používaný AI asistenty vyžaduje samostatný token a bearer hlavičku skutečně používá. Tento token se generuje ve stejné obrazovce s API klíči, ale s REST klíčem není zaměnitelný.

Základní URL, verzování a váš první zápis

Základní URL je https://api.brevo.com/v3/. Verze je v cestě, nikoli v hlavičce, a v3 je aktuální generace. Každá cesta v tomto průvodci je relativní k této základní adrese.

Pro první zápis kontaktu použijte testovací adresu pod Vaší kontrolou, platné ID seznamu a stabilní ID zdroje. Nejprve v Brevo vytvořte atribut FNAME. Se skutečným klíčem tento příklad zapisuje přímo:

curl -X POST https://api.brevo.com/v3/contacts \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "ext_id": "test-source-contact-1",
    "attributes": { "FNAME": "Dev" },
    "listIds": [42],
    "updateEnabled": true,
    "getId": true
  }'

Nahraďte 42 ID Vašeho testovacího seznamu. Znovu načtěte kontakt a ověřte ID, jméno, seznam a blokace. Samotné 2xx nedokazuje očekávaný výsledek.

Endpointy, které skutečně použijete

Kontakty

POST /v3/contacts vytvoří kontakt. Tělo přijímá email, deklarované attributes, listIds a ext_id jako stabilní klíč zdroje. updateEnabled: true aktualizuje existující kontakt a getId: true vyžádá výsledné ID. Brevo tato pole dokumentuje. Používejte stejné ext_id v každém běhu a uložte propojení ID zdroje a Brevo.

Před zápisem určete, který systém vlastní jednotlivé atributy a který seznam přijímá kontakty se souhlasem. listIds zadejte výslovně. V běžném upsertu nikdy nenastavujte emailBlacklisted: false. Brevo varuje, že změna adresy blokovaného kontaktu blokaci zruší. Řešte ji zvlášť. Před přidáním do marketingového seznamu zkontrolujte blokace a odhlášení. Mezi čtením a zápisem zůstává krátké okno; přísné požadavky potřebují poslední kontrolu před odesláním.

Čtení probíhá přes GET /v3/contacts, který stránkuje pomocí limit (výchozí 50, maximum 1000) a offset a podporuje modifiedSince a createdSince v UTC. Inkrementální synchronizace by se měly opírat o modifiedSince místo procházení celého seznamu. Pozor na to, že parametr filter podporuje pouze operátor rovnosti, takže cokoli výraznějšího patří do segmentu.

Pro hromadné načítání přijímá POST /v3/contacts/import parametry fileUrl, fileBody nebo jsonBody, cílí na listIds a běží asynchronně s návratovou hodnotou processId. Brevo dokumentuje maximální velikost těla 10 MB a doporučuje držet se poblíž 8 MB, protože parsování data nafukuje. Předejte notifyUrl, abyste se o výsledku dozvěděli místo dotazování.

Transakční e-maily

POST /v3/smtp/email je tažný kůň. Kromě sender, to, subject a htmlContent stojí za znalost tato pole:

• templateId s params, které nahradí vložený obsah šablonou Brevo a jejími proměnnými. Parametry jednotlivé verze jsou omezeny na 100 KB, kumulativní parametry na 1000 KB.
• messageVersions, které jedním voláním odešle personalizované varianty, až 99 příjemců na verzi.
• tags mohou pomoci přiřadit události doručení k aplikačnímu postupu, který je vyvolal.
• scheduledAt spolu s batchId pro budoucí odeslání, která můžete chtít zrušit jako skupinu.
• headers v Title-Case pro vlastní SMTP hlavičky.

Jediný požadavek přijme nejvýše 2 000 příjemců. Rozdíl mezi tímto endpointem a odesíláním kampaní z pohledu strategie zasílání zpráv rozebírá průvodce transakčními e-maily.

E-mailové kampaně

POST /v3/emailCampaigns vyžaduje name a sender plus přesně jeden zdroj obsahu: htmlContent (minimálně 10 znaků, pod 1 MB), htmlUrl nebo templateId. Publikum se předává v recipients jako listIds nebo segmentIds a scheduledAt používá UTC formát YYYY-MM-DDTHH:mm:ss.SSSZ. Doprovodné cesty pokrývají okamžité odeslání, odeslání testu, změnu stavu a stažení reportu kampaně.

Společnosti, obchody a objekty

CRM v Brevo má dvě překrývající se cesty pro zápis a na správné volbě záleží.

CRM cesty jsou POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} a odpovídající sada pro obchody. Tyto jsou synchronní. PATCH vrátí 204 poté, co je změna aplikována.

API objektů je hromadná cesta: POST /v3/objects/{object_type}/batch/upsert přijímá až 1000 záznamů a 1 MB na požadavek, až 500 atributů na záznam a až 10 asociačních záznamů na typ objektu a záznam. Vrací 202 s processId, což znamená přijato, nikoli aplikováno.

curl -X POST https://api.brevo.com/v3/objects/company/batch/upsert \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "identifiers": { "id": 12345 },
        "attributes": { "domain": "acme.example", "industry": "retail" }
      }
    ]
  }'

Průvodce Brevo CRM pokrývá objektový model z pohledu operátora.

Oficiální SDK

Brevo udržuje klienty pod organizací getbrevo na GitHubu:

Klient pro Node se instaluje jako @getbrevo/brevo:

npm install @getbrevo/brevo

import { BrevoClient } from "@getbrevo/brevo";

// Reconcile uncertain send outcomes before retrying.
const brevo = new BrevoClient({ apiKey: process.env.BREVO_API_KEY, maxRetries: 0 });

const result = await brevo.transactionalEmails.sendTransacEmail({
  subject: "Order confirmed",
  htmlContent: "<html><body><p>Thanks for your order.</p></body></html>",
  sender: { name: "Acme", email: "[email protected]" },
  to: [{ email: "[email protected]", name: "Customer" }],
  tags: ["order-confirmation"],
});

console.log("Message ID:", result.messageId);

Klient pro Python se instaluje přes pip install brevo-python. Pokud kvůli dvěma endpointům raději nechcete nést závislost na SDK, holé HTTP rozhraní je dost malé na přímé volání, což vás navíc izoluje od změn verzí SDK:

Klienta Python nainstalujete příkazem pip install brevo-python. Pro pár endpointů lze volat HTTP přímo:

import os
import requests

BASE = "https://api.brevo.com/v3"
HEADERS = {"api-key": os.environ["BREVO_API_KEY"]}


def upsert_consented_contact(source_id, email, first_name, list_id, consent):
    if not consent:
        raise ValueError("No marketing consent in the source")
    if not source_id or not isinstance(list_id, int):
        raise ValueError("Stable source ID and numeric list ID required")
    # Configure FNAME in Brevo before using this explicit field mapping.
    response = requests.post(
        f"{BASE}/contacts",
        headers=HEADERS,
        json={
            "email": email,
            "ext_id": source_id,
            "attributes": {"FNAME": first_name},
            "listIds": [list_id],
            "updateEnabled": True,
            "getId": True,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json().get("id") if response.content else None

Úspěšná aktualizace může vrátit prázdnou odpověď 204. None pak znamená, že ID musíte získat opětovným načtením kontaktu.

Příklad předpokládá, že volající již zkontroloval souhlas a blokace v Brevo. Nežádá odblokování. Se skutečným klíčem zapisuje přímo do účtu; nejprve jej vyzkoušejte se simulací. Konflikty identifikátorů mohou vracet různé 4xx. Přečtěte odpověď a slaďte ID, nepředpokládejte vždy 409.

Webhooky

Webhooky jsou způsob, jak se dozvíte, co se po odeslání stalo. POST /v3/webhooks jeden vytvoří, s poli url, events, type a volitelně channel (email nebo sms), batched, vlastními headers a objektem auth.

Existují tři typy webhooků s odlišnými slovníky událostí:

• Transakční: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Marketingové: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Příchozí: inboundEmailProcessed a reply, které navíc vyžadují domain.

curl -X POST https://api.brevo.com/v3/webhooks \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/hooks/brevo",
    "type": "transactional",
    "events": ["delivered", "hardBounce", "spam", "unsubscribed"],
    "description": "Deliverability signals"
  }'

Pro změny kontaktů zaregistrujte marketingový webhook s contactUpdated. Brevo v datech událost nazývá contact_updated. Příjemce ověřte tokenem bearer auth nebo vlastními hlavičkami podle bezpečnostní příručky. Tajemství ověřte před zpracováním a neukládejte je do logu.

Uložte deduplikační klíč z typu události, ID kontaktu a časové značky po dobu pokrývající opakované doručení. Čas sám o sobě jedinečný není. Doručení se může opakovat nebo přijít mimo pořadí. Po události znovu načtěte aktuální kontakt a slaďte jej s autoritativním zdrojem. Určete okno replay, po obnově odmítejte staré události a pravidelně provádějte přírůstkovou kontrolu. Webhook hlásí změnu, sám obousměrnou synchronizaci nevytvoří. Průvodce konektory popisuje volby.

Limity požadavků a ošetření chyb

Limity požadavků v Brevo jsou nastaveny pro každý endpoint a každou úroveň tarifu zvlášť a rozptyl mezi endpointy je obrovský.

Brevo dokumentuje x-sib-ratelimit-limit, x-sib-ratelimit-remaining a x-sib-ratelimit-reset na omezených endpointech. Čtěte je i po úspěchu. Při 429 vyčkejte resetu a opakujte jen v pevném rozpočtu pokusů a času. Reset je doba v jednotce okna, obvykle sekundy, nikoli čas Unix.

async function callBrevo(path, init) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const response = await fetch(`https://api.brevo.com/v3${path}`, {
      ...init,
      headers: { "api-key": process.env.BREVO_API_KEY, ...init.headers },
    });
    if (response.status !== 429 || attempt === 2) return response;
    const raw = Number(response.headers.get("x-sib-ratelimit-reset"));
    const seconds = Number.isFinite(raw) && raw > 0 ? raw : 2 ** attempt;
    const delayMs = (seconds + 2 ** attempt) * 1000;
    if (delayMs > 60_000) return response;
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
}

Pokud nutné čekání přesáhne 60 sekund, funkce vrátí 429. Další pokus naplánujte později.

Pomocná funkce je pouze pro požadavky, u nichž jste ověřili bezpečnost opakování. Po nejasné chybě odesílání nejprve slaďte ID zprávy. Logujte stav a limity, nikdy klíč API ani údaje kontaktu.

Neopakujte 4xx naslepo. Referenční dokumentace vytvoření kontaktu uvádí 400 a 425; konflikt nemusí být 409. Po 5xx při zápisu ověřte, zda se změna již provedla.

Testování bez odesílání pošty

Přidejte k transakčnímu odeslání hlavičku X-Sib-Sandbox s hodnotou drop. Brevo požadavek zvaliduje, vrátí 201 s messageId, nic nedoručí a nezapíše žádný záznam do logu e-mailů.

curl -X POST https://api.brevo.com/v3/smtp/email \
  -H "api-key: $BREVO_API_KEY" \
  -H "X-Sib-Sandbox: drop" \
  -H "Content-Type: application/json" \
  -d '{ "sender": { "email": "[email protected]" }, "to": [{ "email": "[email protected]" }], "subject": "Sandbox", "htmlContent": "<p>hi</p>" }'

Mějte jasno v tom, co to dokazuje a co ne. Režim sandbox validuje pouze formát požadavku. Neříká nic o autentizaci odesílatele, vykreslení šablony ani doručitelnosti. Pro integrační testování čehokoli, co se dotýká kontaktů nebo CRM dat, si držte samostatný účet Brevo, protože režim sandbox pokrývá odesílání a nikoli zbytek API.

Před synchronizací kontaktů

• Zvolte stabilní ID zdroje pro ext_id a uložte vrácené Brevo ID.
• Atributy ověřte před zápisem. Brevo může neznámá nebo chybně typovaná pole ignorovat; znovu načtěte testovací kontakt.
• Použijte konkrétní seznam a věrohodný záznam souhlasu. Přeskočte blokované a odhlášené kontakty.
• Počítejte zvlášť přijaté, použité, přeskočené a chybné záznamy. Kód 202 u dávky či objektu potvrzuje zprvu jen přijetí.
• Marketingové webhooky berte jako signály a potom slaďte aktuální stav. Ověřujte, deduplikujte a omezujte replay.
• Sledujte hlavičky limitů a po několika pokusech skončete.

Tajo synchronizuje obchodní data s Brevo. Pokud tuto vrstvu budujete sami, průvodce konektory Brevo porovnává cesty a chyby.