Brevo API: praktický sprievodca pre vývojárov

Import kontaktu môže vrátiť 201 a stále byť nesprávny: stratilo sa ID zdroja, zvolil sa zlý zoznam alebo sa ignorovalo staršie odhlásenie. Sú to rozhodnutia o dátach, nie detaily HTTP.

Sprievodca najprv ukáže funkčnú požiadavku Brevo a potom kontroly pre malú opakovateľnú synchronizáciu.

Čo Brevo API pokrýva

Všetko sa nachádza pod jedným hostiteľom a jednou cestou s verziou. Dokumentácia pre vývojárov delí rozhranie na štyri produktové oblasti:

• Messaging: transakčné e-maily, SMS a WhatsApp vrátane dávkového odosielania, plánovania a aktivity správ.
• Marketingová platforma: kontakty, zoznamy, segmenty a e-mailové kampane.
• eCommerce: produkty, objednávky a sledovanie zákazníckych udalostí.
• Conversations: chatovací widget a programová správa konverzácií.

Tieto oblasti zdieľajú jeden účet, jednu databázu kontaktov a jeden API kľúč. To je pohodlné a občas nebezpečné: skript napísaný s predstavou testovacích dát komunikuje s tými istými kontaktmi, ktorým odosielate kampane.

Transakčné verzus marketingové

Obe rodiny sa správajú natoľko odlišne, že ich zámena je najčastejšou chybou návrhu.

Ak sa ešte len rozhodujete, či je Brevo vôbec tá správna platforma, prehľad platformy pokrýva túto tému.

Autentifikácia a správa kľúčov

Brevo používa jednoduchý API kľúč vo vlastnej hlavičke. Hlavička sa volá api-key, nie Authorization, a nemá predponu Bearer. Na tomto zakopne takmer každý, kto predtým pracoval s iným API na posielanie správ.

OAuth môže pri podporovaných operáciách použiť token Bearer; bežný API kľúč stále patrí do hlavičky api-key.

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

Kľúče sa vytvárajú v aplikácii Brevo v nastaveniach účtu, v sekcii SMTP and API, na karte API keys. Každému kľúču dajte popisný názov naviazaný na systém, ktorý ho používa. Hodnota kľúča sa zobrazí presne raz pri vytvorení, takže ak ju stratíte, vygenerujete nový kľúč namiesto obnovy starého.

Niekoľko praktických pravidiel:

• Vydajte samostatný kľúč pre každé prostredie a každú službu. Zrušenie kompromitovaného kľúča by nikdy nemalo zhodiť tri nesúvisiace systémy.
• Štandardné API kľúče platia pre celý účet. Ku každému kľúču pristupujte ako k plnému prístupu ku kontaktom, odosielaniu a CRM dátam.
• Brevo podporuje aj OAuth 2.0 pre aplikácie, ktoré konajú v mene iných účtov Brevo. Popísané je to spolu s tokom kľúčov v schémach autentifikácie.
• MCP server, ktorý používajú AI asistenti, má vlastný token a ten skutočne používa bearer hlavičku. Vytvára sa na tej istej obrazovke API keys, ale nie je zameniteľný s REST kľúčom.

Základná URL, verzovanie a Váš prvý zápis

Základná URL je https://api.brevo.com/v3/. Verzia je v ceste, nie v hlavičke, a v3 je aktuálna generácia. Každá cesta v tomto sprievodcovi je relatívna voči tejto základnej adrese.

Na prvý zápis kontaktu použite skúšobnú adresu pod Vašou kontrolou, platné ID zoznamu a stabilné ID zdroja. Najprv v Brevo vytvorte atribút FNAME. So skutočným kľúčom príklad zapisuje priamo:

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 Vášho skúšobného zoznamu. Znova načítajte kontakt a overte ID, meno, zoznam a blokovanie. Samotné 2xx nedokazuje očakávaný výsledok.

Endpointy, ktoré budete naozaj používať

Kontakty

POST /v3/contacts vytvorí kontakt. Telo prijíma email, deklarované attributes, listIds a ext_id ako stabilný kľúč zdroja. updateEnabled: true aktualizuje existujúci kontakt a getId: true vyžiada výsledné ID. Brevo tieto polia dokumentuje. Používajte rovnaké ext_id pri každom behu a uložte väzbu ID zdroja a Brevo.

Pred zápisom určte, ktorý systém vlastní jednotlivé atribúty a ktorý zoznam má dostať kontakty so súhlasom. listIds uveďte výslovne. Pri bežnom upserte nikdy nenastavujte emailBlacklisted: false. Brevo upozorňuje, že zmena adresy blokovaného kontaktu blokovanie zruší. Riešte ju osobitne. Pred pridaním do marketingového zoznamu kontrolujte blokovanie a odhlásenie. Medzi čítaním a zápisom zostáva krátke okno; pri prísnych nárokoch treba poslednú kontrolu pred odoslaním.

Čítanie ide cez GET /v3/contacts, ktorý stránkuje pomocou limit (predvolene 50, maximum 1000) a offset a podporuje modifiedSince a createdSince v UTC. Inkrementálne synchronizácie by sa mali opierať o modifiedSince namiesto prechádzania celého zoznamu. Všimnite si, že parameter filter podporuje iba operátor rovnosti, takže čokoľvek výraznejšie patrí do segmentu.

Na hromadné načítanie POST /v3/contacts/import prijíma fileUrl, fileBody alebo jsonBody, cieli na listIds a beží asynchrónne, pričom vracia processId. Brevo dokumentuje maximum 10 MB pre telo požiadavky a odporúča držať sa okolo 8 MB, pretože parsovanie payload nafúkne. Nastavte notifyUrl, aby ste sa o výsledku dozvedeli namiesto opakovaného dopytovania.

Transakčné e-maily

POST /v3/smtp/email je hlavný ťahúň. Okrem sender, to, subject a htmlContent stoja za pozornosť tieto polia:

• templateId s params, ktoré nahradia vložený obsah šablónou Brevo a jej dosadenými premennými. Parametre jednotlivej verzie majú strop 100 KB, kumulatívne parametre 1000 KB.
• messageVersions, ktoré pošlú personalizované varianty v jednom volaní, s najviac 99 príjemcami na verziu.
• tags môžu pomôcť priradiť udalosti doručenia k aplikačnému postupu, ktorý ich vyvolal.
• scheduledAt spolu s batchId pre budúce odoslania, ktoré možno budete chcieť zrušiť ako skupinu.
• headers, v tvare Title-Case, pre vlastné SMTP hlavičky.

Jedna požiadavka prijme najviac 2 000 príjemcov. Rozdielu medzi týmto endpointom a odosielaním kampaní sa venuje sprievodca transakčnými e-mailami z pohľadu stratégie správ.

E-mailové kampane

POST /v3/emailCampaigns vyžaduje name a sender plus presne jeden zdroj obsahu: htmlContent (minimálne 10 znakov, do 1 MB), htmlUrl alebo templateId. Publikum sa uvádza v recipients ako listIds alebo segmentIds a scheduledAt používa UTC formát YYYY-MM-DDTHH:mm:ss.SSSZ. Sprievodné trasy pokrývajú okamžité odoslanie, testovacie odoslanie, aktualizáciu stavu a stiahnutie reportu kampane.

Firmy, obchody a objekty

CRM v Brevo má dve prekrývajúce sa cesty zápisu a správna voľba je dôležitá.

CRM trasy sú POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} a rovnaká sada pre obchody. Tieto sú synchrónne. PATCH vráti 204, keď je zmena aplikovaná.

Objektové API je hromadná cesta: POST /v3/objects/{object_type}/batch/upsert prijme až 1000 záznamov a 1 MB na požiadavku, až 500 atribútov na záznam a až 10 asociačných záznamov na typ objektu a záznam. Vracia 202 s processId, čo znamená prijaté, nie aplikované.

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" }
      }
    ]
  }'

Sprievodca Brevo CRM pokrýva objektový model z pohľadu operátora.

Oficiálne SDK

Brevo udržiava klientov pod organizáciou getbrevo na GitHube:

Klient pre Node sa inštaluje ako @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 pre Python sa inštaluje príkazom pip install brevo-python. Ak nechcete kvôli dvom endpointom ťahať závislosť na SDK, holé HTTP rozhranie je dosť malé na priame volanie, čo Vás zároveň izoluje od zmien verzií SDK:

Klienta Python nainštalujete cez pip install brevo-python. Pri niekoľkých endpointoch možno použiť aj priame HTTP:

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

Úspešná aktualizácia môže vrátiť prázdnu odpoveď 204. None potom znamená, že ID získate novým načítaním kontaktu.

Príklad predpokladá, že volajúci už overil súhlas a blokovanie v Brevo. Nežiada o odblokovanie. So skutočným kľúčom zapisuje priamo; najprv ho skúste s napodobnenými odpoveďami. Konflikty identifikátorov môžu mať rôzne kódy 4xx. Prečítajte odpoveď a zosúlaďte ID, nepredpokladajte vždy 409.

Webhooky

Webhooky sú spôsob, ako sa dozviete, čo sa po odoslaní stalo. POST /v3/webhooks vytvorí jeden, s url, events, type a voliteľne channel (email alebo sms), batched, vlastnými headers a objektom auth.

Existujú tri typy webhookov s odlišnými slovníkmi udalostí:

• 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.
• Prichádzajúce: inboundEmailProcessed a reply, ktoré navyše 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"
  }'

Pre zmeny kontaktov zaregistrujte marketingový webhook s contactUpdated. Brevo udalosť v dátach nazýva contact_updated. Príjemcu overte tokenom bearer auth alebo vlastnými hlavičkami podľa bezpečnostnej príručky. Tajomstvo overte pred spracovaním a nelogujte ho.

Uložte deduplikačný kľúč z typu udalosti, ID kontaktu a časovej značky na dobu pokrývajúcu opakované doručenia. Čas sám o sebe nie je jedinečný. Udalosti sa môžu opakovať alebo prísť mimo poradia. Po udalosti znova načítajte kontakt a zosúlaďte ho s autoritatívnym zdrojom. Určte okno replay, po obnove odmietajte staré udalosti a pravidelne robte prírastkovú kontrolu. Webhook hlási zmenu, sám obojsmernú synchronizáciu netvorí. Sprievodca konektormi opisuje voľby.

Limity požiadaviek a spracovanie chýb

Limity požiadaviek v Brevo sú nastavené pre každý endpoint a každú úroveň plánu a rozptyl medzi endpointmi je obrovský.

Brevo dokumentuje x-sib-ratelimit-limit, x-sib-ratelimit-remaining a x-sib-ratelimit-reset na obmedzených endpointoch. Čítajte ich aj po úspechu. Pri 429 počkajte na reset a opakujte len v pevnom limite pokusov a času. Reset je trvanie v jednotke okna, spravidla v sekundách, nie č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));
  }
}

Ak potrebné čakanie presiahne 60 sekúnd, funkcia vráti 429. Ďalší pokus naplánujte neskôr.

Pomocná funkcia je určená len na požiadavky, pri ktorých ste preverili bezpečnosť opakovania. Po nejasnej chybe odoslania najprv zosúlaďte ID správy. Logujte stav a limity, nie kľúč API ani údaje kontaktov.

Neopakujte 4xx naslepo. Referencia vytvorenia kontaktu uvádza 400 a 425; konflikt nemusí byť 409. Po 5xx pri zápise overte, či zmena už prebehla.

Testovanie bez odoslania pošty

Do transakčného odoslania pridajte hlavičku X-Sib-Sandbox s hodnotou drop. Brevo požiadavku overí, vráti 201 s messageId, nič nedoručí a nezapíše žiadny e-mailový záznam.

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>" }'

Pochopte, čo to dokazuje a čo nie. Režim sandbox overuje iba formát požiadavky. Nehovorí nič o autentifikácii odosielateľa, vykreslení šablóny ani o doručiteľnosti. Pre integračné testovanie čohokoľvek, čo sa dotýka kontaktov alebo CRM dát, si držte samostatný účet Brevo, pretože režim sandbox pokrýva odosielanie a nie zvyšok API.

Pred synchronizáciou kontaktov

• Zvoľte stabilné ID zdroja pre ext_id a uložte vrátené Brevo ID.
• Atribúty overte pred zápisom. Brevo môže neznáme alebo chybne typované polia ignorovať; znova načítajte skúšobný kontakt.
• Použite konkrétny zoznam a dôveryhodný záznam súhlasu. Preskočte blokovaných a odhlásených.
• Počítajte osobitne prijaté, použité, preskočené a chybné záznamy. Kód 202 pri dávke či objekte najprv potvrdzuje iba prijatie.
• Marketingové webhooky berte ako signály a potom zosúlaďte aktuálny stav. Overujte, deduplikujte a obmedzujte replay.
• Sledujte hlavičky limitov a po niekoľkých pokusoch skončite.

Tajo synchronizuje obchodné údaje s Brevo. Ak túto vrstvu budujete sami, sprievodca konektormi Brevo porovnáva cesty a chyby.