Brevo API: praktický průvodce pro vývojáře
Průvodce Brevo API pro vývojáře: autentizace, základní URL, kontakty, transakční e-maily, kampaně, CRM objekty, webhooky, limity požadavků a reálná omezení.
Brevo nabízí jedno REST API, které pokrývá transakční zprávy, marketingové kampaně, data o kontaktech i CRM záznamy. Než první požadavek vrátí 201, uplynou asi dvě minuty. Než postavíte produkční integraci, která tiše neztrácí data, uplyne podstatně více času, protože několik nejdůležitějších omezení je buď nezdokumentovaných, nebo si odporuje s tím, co o sobě API hlásí.
Tento průvodce pokrývá obě poloviny: endpointy, SDK a autentizaci, které potřebujete hned první den, a limity platformy, které musíte zohlednit v návrhu ještě před nasazením.
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.
| Transakční | Marketingové | |
|---|---|---|
| Hlavní endpoint | POST /v3/smtp/email | POST /v3/emailCampaigns |
| Adresace | Explicitní příjemci v požadavku | listIds nebo segmentIds |
| Spouštěč | Vaše aplikace, v reálném čase | Naplánované nebo odeslané na vyžádání |
| Typický tvar objemu | Souvislý, po jedné zprávě | Nárazový, jedno velké odeslání |
| Postoj k limitům požadavků | Velmi vysoký, 1 000 požadavků za sekundu na standardních tarifech | Nízký, endpointy kampaní spadají pod obecný strop |
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.
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.
První zápis je poučnější než první čtení, protože prověří ty části účtu, které bývají špatně nastavené, zejména ověřené odesílatele:
curl -X POST https://api.brevo.com/v3/smtp/email \ -H "api-key: $BREVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sender": { "name": "Ops", "email": "[email protected]" }, "to": [{ "email": "[email protected]", "name": "Dev" }], "subject": "First transactional send", "htmlContent": "<html><body><p>It works.</p></body></html>", "tags": ["smoke-test"] }'Úspěšné odeslání vrátí 201 s messageId. Naplánované odeslání vrátí 202.
Endpointy, které skutečně použijete
Kontakty
POST /v3/contacts vytvoří kontakt. Tělo přijímá email, mapu attributes pro vlastní pole, listIds, ext_id pro váš vlastní externí klíč a dva příznaky, na kterých v praxi záleží nejvíc: updateEnabled, který z volání udělá upsert, a getId, díky němuž odpověď vrátí id kontaktu.
Č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:
templateIdsparams, 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, které byste měli nastavovat vždy. Tagy se vracejí v událostech webhooků a jsou jediným levným způsobem, jak spojit událost doručení s částí kódu, která ji vyvolala.scheduledAtspolu sbatchIdpro budoucí odeslání, která můžete chtít zrušit jako skupinu.headersv 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:
| Jazyk | Repozitář |
|---|---|
| Node.js | github.com/getbrevo/brevo-node |
| Python | github.com/getbrevo/brevo-python |
| PHP | github.com/getbrevo/brevo-php |
| Java | github.com/getbrevo/brevo-java |
| C# | github.com/getbrevo/brevo-csharp |
| Go | github.com/getbrevo/brevo-go |
| Ruby | github.com/getbrevo/brevo-ruby |
Klient pro Node se instaluje jako @getbrevo/brevo:
npm install @getbrevo/brevoimport { BrevoClient } from "@getbrevo/brevo";
const brevo = new BrevoClient({ apiKey: process.env.BREVO_API_KEY });
const result = await brevo.transactionalEmails.sendTransacEmail({ subject: "Order confirmed", htmlContent: "<html><body><p>Thanks for your order.</p></body></html>", 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:
import osimport requests
BASE = "https://api.brevo.com/v3"HEADERS = { "api-key": os.environ["BREVO_API_KEY"], "Content-Type": "application/json",}
def upsert_contact(email, attributes, list_ids): response = requests.post( f"{BASE}/contacts", headers=HEADERS, json={ "email": email, "attributes": attributes, "listIds": list_ids, "updateEnabled": True, }, timeout=30, ) response.raise_for_status() return responseExistuje také MCP server na adrese https://mcp.brevo.com/v1/brevo/mcp pro AI asistenty, autentizovaný bearer tokenem vygenerovaným ve stejné obrazovce nastavení. Hodí se pro průzkum a dotazy na účet, nikoli pro produkční datové cesty.
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í:
inboundEmailProcessedareply, 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" }'Tři věci si pohlídejte. Zaprvé, jeden účet může mít nejvýše 40 webhooků napříč všemi typy, takže směrujte podle události uvnitř svého handleru místo registrace jednoho endpointu na událost. Zadruhé, při očekávaném objemu použijte příznak batched, protože jeden požadavek nesoucí mnoho událostí se zpracovává výrazně levněji než mnoho požadavků. Zatřetí, chraňte příjemce: Brevo zveřejňuje své odesílací rozsahy IP adres a omezení vašeho endpointu na tyto rozsahy je dokumentovaný postup. Jako druhou vrstvu přidejte vlastní sdílené tajemství přes pole headers.
Handlery musí být idempotentní. Jako deduplikační klíč použijte id zprávy plus typ události plus časové razítko.
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ý.
| Endpoint | Standard | Professional a Enterprise |
|---|---|---|
POST /v3/smtp/email | 1 000 RPS | 2 000 RPS |
POST /v3/transactionalSMS/send | 150 RPS | 200 RPS |
/v3/contacts/... | 10 RPS, 36 000 RPH | 20 RPS, 72 000 RPH |
POST /v3/events | 10 RPS, 36 000 RPH | vyšší na Enterprise |
GET /v3/smtp/emails | 2 RPS, 7 200 RPH | 3 RPS, 10 800 RPH |
| Vše ostatní | 100 RPH | 200 RPH |
Bolí právě ten poslední řádek. Odesílání je fakticky neměřené, zatímco správa kampaní, čtení z CRM a většina administrativních volání sdílejí na standardních tarifech rozpočet 100 požadavků za hodinu. Naivní doplnění dat, které před každým zápisem načte záznam společnosti, vyčerpá hodinovou kvótu za necelé dvě minuty.
Každá odpověď nese x-sib-ratelimit-limit, x-sib-ratelimit-remaining a x-sib-ratelimit-reset. Čtěte je při úspěchu, nejen při selhání. Překročení limitu vrátí 429 a správnou reakcí je počkat interval z hlavičky reset a poté použít exponenciální odklad s náhodným rozptylem.
async function callBrevo(path, init, attempt = 0) { const response = await fetch(`https://api.brevo.com/v3${path}`, { ...init, headers: { "api-key": process.env.BREVO_API_KEY, "Content-Type": "application/json", ...init.headers }, });
if (response.status === 429 && attempt < 5) { const reset = Number(response.headers.get("x-sib-ratelimit-reset") || 1); const backoff = Math.pow(2, attempt) * 250 + Math.random() * 250; await new Promise((r) => setTimeout(r, reset * 1000 + backoff)); return callBrevo(path, init, attempt + 1); }
return response;}Opakujte 429 a 5xx. Nikdy neopakujte 400 nebo 409 naslepo, protože obojí obvykle znamená, že požadavek je špatný, nikoli předčasný, a 409 zvlášť vyžaduje jinou akci, nikoli opakování.
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.
Limity, které formují návrh vaší integrace
Toto jsou omezení, která se objeví teprve tehdy, když integrace běží proti reálnému účtu v objemu. Několik z nich si odporuje s tím, co o sobě API tvrdí. Žádné z nich není vyjednatelné, takže jediná rozumná reakce je navrhnout řešení tak, aby s nimi počítalo.
Společnosti vyžadují doménu a na jednu doménu připadá jen jedna společnost
GET /v3/crm/attributes/companies hlásí každý atribut jako nepovinný a reference pro vytvoření společnosti uvádí jako povinné pouze name. V praxi POST /v3/companies bez neprázdného atributu domain vrátí 400 se zprávou o chybějících povinných výchozích atributech. Prázdný řetězec selže stejně jako úplné vynechání.
Hůř, jedinečnost domény je vynucována. Druhá společnost na doméně, která je již použita, vrátí 409. Pro B2B commerce je to strukturální problém: dceřiné firmy sdílející jednu e-mailovou doménu nákupčího nemohou v Brevo existovat jako samostatné společnosti. Také samotná synchronizace kontaktu stačí k tomu, aby se na e-mailové doméně toho kontaktu objevila společnost, takže vytvoření může kolidovat se společností, kterou nikdo výslovně nevytvořil. Správný handler při 409 existující společnost převezme místo selhání nebo opakování.
Nedeklarované atributy se tiše zahazují
Toto je nejnebezpečnější chování celé platformy a Brevo jej dokumentuje zcela otevřeně: pokud se atribut objeví v požadavku, ale nebyl předtím definován ve schématu objektu, nestane se nic. Žádná chyba, žádné vytvoření atributu, žádné varování.
Odpověď 2xx tedy není důkazem, že vaše data dorazila. Než začnete zapisovat, přečtěte si schéma, ve vlastním klientovi zahazujte vše nedeklarované a raději odmítněte spustit synchronizaci, jejíž atributy neexistují, než abyste měsíc zapisovali půlku záznamu, než si toho někdo všimne.
Filtry podle atributů jsou přijaty a ignorovány
GET /v3/companies?filters[attributes.domain]=... vrátí 200 a filtr ignoruje. Dva zcela odlišné filtry vrátí stejné záznamy. Touto cestou neexistuje funkční způsob, jak společnost vyhledat podle atributu.
V kombinaci s tím, že nefiltrovaný seznam na velkých účtech vyprší chybou 504 při jakékoli velikosti stránky, může být existující společnost dokumentovanou cestou skutečně nedohledatelná. Obchvatem je projít GET /v3/objects/company/records s sort=desc, což je rychlé, stránkované a vrací atributy, omezené na rozumný počet stránek. Společnost, která právě vyvolala 409, byla téměř vždy vytvořena před chvílí, takže procházení od nejnovějších ji najde rychle.
Milion záznamů na typ objektu a žádné hromadné mazání
POST /v3/objects/{type}/batch/upsert vrátí 400, jakmile typ objektu obsahuje milion záznamů. Blokuje aktualizace stejně jako vytváření: adresování existujícího záznamu jeho vlastním číselným id selže identicky. Celá cesta zápisu do objektů se uzavře najednou.
Návrat pod strop je pomalý, protože POST /v3/objects/{type}/batch/delete vrací 403 pro standardní typy objektů Brevo, jako je company. Jedinou cestou je DELETE /v3/companies/{id}, jeden záznam na volání zhruba za 156 ms. Vyčištění 124 000 záznamů tímto způsobem trvalo hodiny při 20 paralelních workerech. Sledujte počet záznamů podle plánu místo toho, abyste strop objevili až přes selhanou synchronizaci, a aktualizace ve velkém objemu směrujte přes PATCH /v3/companies/{id}, který takový limit nemá.
ext_id je id Brevo, nikoli vaše
U záznamů objektů obsahuje identifiers.ext_id vlastní CRM id společnosti v Brevo, řetězec ve stylu Mongo. Není to volný externí klíč. Použití ext_id nastaveného na identifikátor vaší platformy jako klíče pro upsert vytváří duplicity místo párování. Vaše externí id patří do vlastního deklarovaného atributu.
Upserty objektů jsou asynchronní, zápisy do CRM nikoli
batch/upsert vrátí 202 a processId a aplikuje se až později. Neexistující id selže asynchronně a volajícímu přesto vrátí 202. PATCH /v3/companies/{id} vrátí 204 a aplikuje se synchronně. Pokud vaše synchronizace hlásí úspěch, bez následného čtení si to slovo zaslouží pouze synchronní cesta.
Krátký kontrolní seznam pro integraci
- Samostatné API klíče pro každou službu a každé prostředí, rotované při personálních změnách.
- Všechny zápisy jdou přes jednoho klienta, který čte hlavičky s limity a při 429 zpomaluje.
- Schéma atributů se ověřuje při startu a synchronizace odmítne běžet, pokud její atributy chybí.
- 409 při vytvoření společnosti znamená převzít, nikoli opakovat.
- Hromadné cesty používají API objektů kvůli propustnosti a CRM cesty pro cokoli, co musí být potvrzeno.
- Webhooky jsou idempotentní, dávkované, omezené na IP adresy a nesou hlavičku se sdíleným tajemstvím.
- Inkrementální synchronizace kontaktů používají
modifiedSince, nikoli procházení celého seznamu.
Postavit a udržovat tuto vrstvu je skutečná inženýrská práce: ověřování schématu, odklady, logika převzetí, rekonciliace. Tajo existuje proto, aby ji pohltilo, a udržuje data ze Shopify a e-commerce v souladu s kontakty, společnostmi a událostmi v Brevo, aniž by kdokoli ručně psal logiku opakování a deduplikace. Pokud si to naopak zapojujete sami, průvodce integrací Brevo prochází rozhodnutí o datovém modelu, která přicházejí ještě před kódem.
Klíčové poznatky
- API je jedno REST rozhraní na adrese
https://api.brevo.com/v3/, autentizované hlavičkouapi-keymísto bearer tokenu. - Limity požadavků jsou divoce nevyrovnané: odesílání je fakticky neměřené, zatímco většina ostatních endpointů sdílí na standardních tarifech 100 požadavků za hodinu.
- Oficiální SDK existují pro sedm jazyků, ale HTTP rozhraní je dost jednoduché na přímé volání, pokud potřebujete jen pár endpointů.
- Režim sandbox validuje pouze formát požadavku, takže si pro testování čehokoli nad rámec odesílání držte samostatný účet.
- Odpověď 2xx nedokazuje, že se zápis aplikoval. Nedeklarované atributy se tiše zahazují a upserty objektů jsou asynchronní.
- Navrhujte řešení s ohledem na pevná omezení: jedna společnost na doménu, milion záznamů na typ objektu, žádné hromadné mazání standardních objektů a filtry podle atributů, které tiše nedělají nic.