Brevo API: praktičan vodič za programere

Uvoz kontakta može vratiti 201, a ipak biti pogrešan: izgubljen je ID izvora, izabrana je pogrešna lista ili zanemarena ranija odjava. To su odluke o podacima, ne HTTP detalji.

Vodič prvo prikazuje radni Brevo poziv, a zatim kontrole za malu ponovljivu sinhronizaciju.

Šta Brevo API pokriva

Sve živi pod jednim hostom i jednom putanjom verzije. Programerska dokumentacija grupiše tu površinu u četiri proizvodne oblasti:

• Poruke: transakcioni imejl, SMS i WhatsApp, uključujući grupna slanja, zakazivanje i aktivnost poruka.
• Marketinška platforma: kontakti, liste, segmenti i imejl kampanje.
• eCommerce: proizvodi, porudžbine i praćenje događaja kupaca.
• Conversations: čet vidžet i programsko upravljanje razgovorima.

Te oblasti dele jedan nalog, jednu bazu kontakata i jedan API ključ. To je praktično i povremeno opasno: skripta napisana prema zamišljenoj test verziji podataka razgovara sa istim kontaktima kojima šaljete kampanje.

Transakciono naspram marketinškog

Ove dve porodice se dovoljno razlikuju u ponašanju da je njihovo mešanje najčešća greška u projektovanju.

Ako još odlučujete da li je Brevo uopšte prava platforma, pregled platforme pokriva tu temu.

Autentifikacija i upravljanje ključevima

Brevo koristi običan API ključ u prilagođenom zaglavlju. Zaglavlje se zove api-key, ne Authorization, i nema prefiks Bearer. Na tome se saplete skoro svako ko je prvo koristio neki drugi API za poruke.

OAuth može da koristi Bearer token za podržane operacije; običan API ključ i dalje šaljite u zaglavlju api-key.

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

Ključevi se generišu u aplikaciji Brevo, u podešavanjima naloga, u odeljku SMTP and API, na kartici API keys. Dajte svakom ključu opisno ime vezano za sistem koji ga koristi. Vrednost ključa prikazuje se tačno jednom prilikom generisanja, pa ako je izgubite, generišete novi umesto da vraćate stari.

Nekoliko praktičnih pravila:

• Izdajte poseban ključ po okruženju i po servisu. Povlačenje kompromitovanog ključa nikada ne bi smelo da obori tri nepovezana sistema.
• Standardni API ključevi važe za ceo nalog. Tretirajte svaki ključ kao pun pristup kontaktima, slanju i CRM podacima.
• Brevo podržava i OAuth 2.0 za aplikacije koje deluju u ime drugih Brevo naloga, što je opisano uz tok sa ključevima u dokumentu authentication schemes.
• MCP server koji koriste AI asistenti uzima poseban token i zaista koristi bearer zaglavlje. Taj token se generiše na istom ekranu sa API ključevima, ali nije zamenljiv sa REST ključem.

Osnovni URL, verzionisanje i vaš prvi upis

Osnovni URL je https://api.brevo.com/v3/. Verzija je u putanji, a ne u zaglavlju, i v3 je aktuelna generacija. Svaka putanja u ovom vodiču data je u odnosu na tu osnovu.

Za prvi upis kontakta koristite probnu adresu koju kontrolišete, važeći ID liste i stabilan ID izvora. Prvo u Brevu napravite atribut FNAME. Sa pravim ključem primer upisuje direktno:

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

Zamenite 42 ID-jem probne liste. Ponovo pročitajte kontakt i proverite ID, ime, listu i blokade. Sam 2xx ne dokazuje očekivani ishod.

Krajnje tačke koje ćete zaista koristiti

Kontakti

POST /v3/contacts pravi kontakt. Telo prima email, deklarisane attributes, listIds i ext_id kao stabilan ključ izvora. updateEnabled: true ažurira postojeći kontakt, a getId: true traži konačni ID. Brevo dokumentuje polja. Koristite isti ext_id svaki put i čuvajte vezu između ID-ja izvora i Breva.

Pre upisa odredite koji sistem upravlja kojim atributom i koja lista dobija kontakte sa saglasnošću. Navedite listIds izričito. Nikad ne postavljajte emailBlacklisted: false u običnom upsertu. Brevo upozorava da promena adrese blokiranog kontakta uklanja blokadu. Rešavajte je zasebno. Pre dodavanja na marketinšku listu proverite blokade i odjave. Između čitanja i upisa ostaje kratak period; strogi zahtevi traže poslednju proveru pre slanja.

Čitanja idu kroz GET /v3/contacts, koji straničari uz limit (podrazumevano 50, najviše 1000) i offset, i podržava modifiedSince i createdSince u UTC vremenu. Inkrementalne sinhronizacije treba da se oslone na modifiedSince umesto da prolaze kroz celu listu. Imajte u vidu da parametar filter podržava samo operator jednakosti, pa sve izražajnije spada u segment.

Za masovno učitavanje, POST /v3/contacts/import prihvata fileUrl, fileBody ili jsonBody, cilja listIds i radi asinhrono, vraćajući processId. Brevo dokumentuje maksimum od 10 MB za telo i preporučuje da ostanete oko 8 MB, jer parsiranje uvećava sadržaj. Prosledite notifyUrl da biste saznali ishod umesto da anketirate status.

Transakcioni imejl

POST /v3/smtp/email je radni konj. Osim sender, to, subject i htmlContent, vredi znati sledeća polja:

• templateId sa params, koji zamenjuje ugrađeni sadržaj šablonom platforme Brevo i njegovim zamenama promenljivih. Parametri pojedinačne verzije ograničeni su na 100 KB, a kumulativni na 1000 KB.
• messageVersions, koji šalje personalizovane varijante u jednom pozivu, sa najviše 99 primalaca po verziji.
• tags mogu pomoći da povežete događaje isporuke sa tokom aplikacije koji ih je izazvao.
• scheduledAt uz batchId, za buduća slanja koja ćete možda želeti da otkažete kao grupu.
• headers, u obliku Title-Case, za prilagođena SMTP zaglavlja.

Jedan zahtev prihvata najviše 2.000 primalaca. Za razliku između ove krajnje tačke i slanja kampanja, vodič za transakcioni imejl daje pogled iz ugla strategije poruka.

Imejl kampanje

POST /v3/emailCampaigns zahteva name i sender, plus tačno jedan izvor sadržaja: htmlContent (najmanje 10 znakova, ispod 1 MB), htmlUrl ili templateId. Publika ide u recipients kao listIds ili segmentIds, a scheduledAt koristi UTC format YYYY-MM-DDTHH:mm:ss.SSSZ. Prateće rute pokrivaju trenutno slanje, slanje testa, izmenu statusa i preuzimanje izveštaja o kampanji.

Kompanije, poslovi i objekti

CRM u platformi Brevo ima dve putanje za upis koje se preklapaju, i ispravan izbor je bitan.

CRM rute su POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} i istovetan skup za poslove. One su sinhrone. PATCH vraća 204 čim je izmena primenjena.

API za objekte je putanja za masovni rad: POST /v3/objects/{object_type}/batch/upsert prima do 1000 zapisa i 1 MB po zahtevu, do 500 atributa po zapisu i do 10 povezanih zapisa po tipu objekta po zapisu. Vraća 202 sa poljem processId, što znači prihvaćeno, a ne primenjeno.

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

Vodič kroz Brevo CRM pokriva model objekata iz ugla operatera.

Zvanični SDK-ovi

Brevo održava klijente u GitHub organizaciji getbrevo:

Node klijent se instalira kao @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);

Python klijent se instalira sa pip install brevo-python. Ako ne želite da nosite zavisnost od SDK-a zbog dve krajnje tačke, sirova HTTP površina je dovoljno mala da je pozovete direktno, što vas ujedno štiti od stalnih izmena verzija SDK-a:

Python klijent se instalira sa pip install brevo-python. Za nekoliko krajnjih tačaka možete direktno pozvati 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

Uspešno ažuriranje može vratiti prazan odgovor 204. None tada znači da za ID morate ponovo pročitati kontakt.

Primer pretpostavlja da je pozivalac već proverio saglasnost i blokade u Brevu. Ne traži uklanjanje blokade. Sa pravim ključem piše u nalog; prvo ga ispitajte simulacijom. Sukobi identifikatora mogu dati različite 4xx kodove. Pročitajte odgovor i uskladite ID-jeve, ne očekujte uvek 409.

Webhookovi

Webhookovi su način da saznate šta se dogodilo posle slanja. POST /v3/webhooks kreira jedan, sa url, events, type i opciono channel (email ili sms), batched, prilagođenim headers i objektom auth.

Postoje tri tipa webhookova sa različitim rečnicima događaja:

• Transakcioni: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Marketinški: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Dolazni: inboundEmailProcessed i reply, koji dodatno zahtevaju 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"
  }'

Za promene kontakata registrujte marketinški webhook sa contactUpdated. Brevo događaj u podacima zove contact_updated. Primaoca potvrdite bearer tokenom auth ili svojim zaglavljima prema bezbednosnom vodiču. Tajnu proverite pre obrade i ne beležite je.

Sačuvajte ključ za uklanjanje duplikata od tipa događaja, ID-ja kontakta i vremenske oznake tokom perioda ponovne isporuke. Sama oznaka nije jedinstvena. Događaji se mogu ponoviti ili stići mimo redosleda. Posle događaja ponovo pročitajte kontakt i uskladite ga s pouzdanim izvorom. Odredite prozor reprodukcije, nakon oporavka odbacite stare događaje i redovno radite inkrementalnu proveru. Webhook signalizira promenu, sam ne pravi dvosmernu sinhronizaciju. Vodič za konektore opisuje izbor.

Ograničenja broja zahteva i obrada grešaka

Ograničenja broja zahteva u platformi Brevo postavljaju se po krajnjoj tački i po nivou plana, a raspon između krajnjih tačaka je ogroman.

Brevo dokumentuje x-sib-ratelimit-limit, x-sib-ratelimit-remaining i x-sib-ratelimit-reset na ograničenim tačkama. Čitajte ih i posle uspeha. Pri 429 čekajte reset, pa ponavljajte samo u granicama broja pokušaja i vremena. Reset je trajanje u jedinici vremenskog prozora, obično u sekundama, ne Unix vreme.

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));
  }
}

Ako potrebno čekanje prelazi 60 sekundi, funkcija vraća 429. Sledeći pokušaj zakažite kasnije.

Pomoćna funkcija služi samo zahtevima čije ste ponavljanje proverili kao bezbedno. Posle nejasne greške slanja prvo uskladite ID poruke. Beležite status i zaglavlja, ne API ključ ili kontakt podatke.

Ne ponavljajte 4xx naslepo. Referenca za pravljenje kontakta navodi 400 i 425; sukob ne mora biti 409. Posle 5xx pri upisu proverite da li je promena već sprovedena.

Testiranje bez slanja pošte

Dodajte zaglavlje X-Sib-Sandbox sa vrednošću drop u transakciono slanje. Brevo proverava ispravnost zahteva, vraća 201 sa poljem messageId, ne isporučuje ništa i ne upisuje zapis u imejl dnevnik.

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

Shvatite šta ovo dokazuje, a šta ne. Sandbox režim proverava samo format zahteva. On ne govori ništa o autentifikaciji pošiljaoca, iscrtavanju šablona ili isporučivosti. Držite poseban Brevo nalog za integraciono testiranje svega što dodiruje kontakte ili CRM podatke, jer sandbox režim pokriva slanje, a ne ostatak API-ja.

Proverite pre sinhronizacije kontakata

• Izaberite stabilan ID izvora za ext_id i sačuvajte vraćeni Brevo ID.
• Proverite atribute pre upisa. Brevo može zanemariti nepoznata ili pogrešno tipizirana polja; ponovo pročitajte probni kontakt.
• Koristite određenu listu i pouzdan dokaz saglasnosti. Preskočite blokirane i odjavljene.
• Posebno brojite prihvaćene, primenjene, preskočene i neuspele zapise. Kod 202 za grupe ili objekte prvo znači samo prihvatanje.
• Marketinške webhookove koristite kao signale i zatim uskladite stanje. Potvrdite, uklonite duplikate i ograničite reprodukciju.
• Pratite zaglavlja ograničenja i stanite posle nekoliko pokušaja.

Tajo sinhronizuje trgovinske podatke sa Brevom. Ako taj sloj gradite sami, vodič za Brevo konektore poredi putanje i greške.