Brevo API: praktični vodič za razvojne inženjere

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

Vodič najprije pokazuje radni Brevo poziv, a zatim provjere za malu ponovljivu sinkronizaciju.

Što Brevo API pokriva

Sve živi pod jednim hostom i jednom verzijskom putanjom. Razvojna dokumentacija grupira površinu u četiri proizvodna područja:

• Slanje poruka: transakcijska e-pošta, SMS i WhatsApp, uključujući skupna slanja, raspoređivanje i aktivnost poruka.
• Marketinška platforma: kontakti, popisi, segmenti i kampanje e-pošte.
• eCommerce: proizvodi, narudžbe i praćenje događaja kupaca.
• Conversations: chat widget i programsko upravljanje razgovorima.

Ta područja dijele jedan račun, jednu bazu kontakata i jedan API ključ. To je praktično i povremeno opasno: skripta napisana prema pretpostavci o testnim podacima razgovara s istim kontaktima kojima šaljete kampanje.

Transakcijsko naspram marketinškog

Te se dvije obitelji ponašaju dovoljno različito da je njihovo miješanje najčešća pogreška u dizajnu.

Ako još odlučujete je li Brevo uopće prava platforma za vas, pregled platforme pokriva to područje.

Autentifikacija i upravljanje ključevima

Brevo koristi običan API ključ u prilagođenom zaglavlju. Zaglavlje se zove api-key, ne Authorization, i nema prefiksa Bearer. Na tome se spotakne gotovo svatko tko je prije radio s nekim drugim API-jem za slanje poruka.

OAuth može upotrijebiti 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 generiraju u aplikaciji Brevo, u postavkama računa, u odjeljku SMTP and API, na kartici API keys. Svakom ključu dajte opisno ime vezano uz sustav koji ga koristi. Vrijednost ključa prikazuje se točno jednom pri generiranju, pa ako je izgubite, generirate novi umjesto da vraćate stari.

Nekoliko praktičnih pravila:

• Izdajte zaseban ključ po odredištu implementacije i po servisu. Opoziv kompromitiranog ključa nikada ne bi smio srušiti tri nepovezana sustava.
• Standardni API ključevi vrijede za cijeli račun. Svaki ključ tretirajte kao potpuni pristup kontaktima, slanju i CRM podacima.
• Brevo podržava i OAuth 2.0 za aplikacije koje djeluju u ime drugih Brevo računa, što je opisano uz tijek s ključevima u dokumentu authentication schemes.
• MCP poslužitelj koji koriste AI asistenti uzima zaseban token i doista koristi bearer zaglavlje. Taj se token generira na istom zaslonu s API ključevima, ali nije zamjenjiv s REST ključem.

Osnovni URL, verzioniranje i vaš prvi zapis

Osnovni URL je https://api.brevo.com/v3/. Verzija je u putanji, a ne u zaglavlju, i v3 je aktualna generacija. Svaka putanja u ovom vodiču relativna je prema toj osnovi.

Za prvi zapis kontakta upotrijebite testnu adresu pod vašim nadzorom, valjan ID popisa i stabilan ID izvora. Prvo u Brevu stvorite atribut FNAME. Sa stvarnim ključem primjer piše izravno:

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

Zamijenite 42 ID-jem testnog popisa. Ponovno pročitajte kontakt i provjerite ID, ime, popis i blokade. Sam 2xx ne dokazuje očekivani rezultat.

Krajnje točke koje ćete stvarno koristiti

Kontakti

POST /v3/contacts stvara kontakt. Tijelo prima email, deklarirane 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 dokumentira ta polja. Upotrebljavajte isti ext_id pri svakom pokretanju i čuvajte vezu između ID-ja izvora i Breva.

Prije zapisa odredite koji sustav upravlja kojim atributom i koji popis prima kontakte s privolom. Navedite listIds izričito. Nikad ne postavljajte emailBlacklisted: false pri običnom upsertu. Brevo upozorava da promjena adrese blokiranog kontakta uklanja blokadu. Rješavajte je posebno. Prije dodavanja na marketinški popis provjerite blokade i odjave. Između čitanja i pisanja ostaje kratko razdoblje; strogi zahtjevi traže posljednju provjeru prije slanja.

Čitanja idu kroz GET /v3/contacts, koji stranicira uz limit (zadano 50, najviše 1000) i offset, a podržava modifiedSince i createdSince u UTC-u. Inkrementalne sinkronizacije trebale bi se oslanjati na modifiedSince umjesto na prolazak kroz cijeli popis. Imajte na umu da parametar filter podržava samo operator jednakosti, pa sve izražajnije pripada u segment.

Za skupno učitavanje POST /v3/contacts/import prima fileUrl, fileBody ili jsonBody, cilja listIds i izvodi se asinkrono, vraćajući processId. Brevo dokumentira najveće tijelo od 10 MB i preporučuje da ostanete blizu 8 MB jer parsiranje napuhuje sadržaj. Navedite notifyUrl da saznate ishod umjesto da ispitujete stanje u petlji.

Transakcijska e-pošta

POST /v3/smtp/email je radni konj. Osim sender, to, subject i htmlContent, vrijedi znati i ova polja:

• templateId uz params, koji zamjenjuje ugrađeni sadržaj predloškom iz platforme Brevo i njegovim zamjenama varijabli. Parametri pojedinačne verzije ograničeni su na 100 KB, a kumulativni parametri na 1000 KB.
• messageVersions, koji jednim pozivom šalje personalizirane varijante, uz najviše 99 primatelja po verziji.
• tags mogu pomoći povezati događaje isporuke s tijekom aplikacije koji ih je uzrokovao.
• scheduledAt uz batchId, za buduća slanja koja ćete možda htjeti otkazati kao grupu.
• headers, u obliku Title-Case, za prilagođena SMTP zaglavlja.

Jedan zahtjev prima najviše 2.000 primatelja. Za razliku između ove krajnje točke i slanja kampanja, vodič za transakcijsku e-poštu donosi pogled iz perspektive strategije poruka.

Kampanje e-pošte

POST /v3/emailCampaigns zahtijeva name i sender, uz toč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, ažuriranje statusa i dohvat izvještaja o kampanji.

Tvrtke, poslovi i objekti

CRM platforme Brevo ima dvije preklapajuće putanje za zapisivanje i ispravan izbor je važan.

CRM rute su POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} i ekvivalentni skup za poslove. One su sinkrone. PATCH vraća 204 čim je promjena primijenjena.

Objects API je skupna putanja: POST /v3/objects/{object_type}/batch/upsert prima do 1000 zapisa i 1 MB po zahtjevu, do 500 atributa po zapisu i do 10 povezanih zapisa po tipu objekta po zapisu. Vraća 202 s vrijednošću processId, što znači prihvaćeno, a ne primijenjeno.

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č za Brevo CRM pokriva model objekata iz operaterske perspektive.

Službeni SDK-ovi

Brevo održava klijente u GitHub organizaciji getbrevo:

Node klijent instalira se 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 instalira se s pip install brevo-python. Ako radije ne biste nosili ovisnost o SDK-u zbog dvije krajnje točke, sirova HTTP površina dovoljno je mala da je pozivate izravno, što vas ujedno štiti od stalnih promjena verzija SDK-a:

Python klijent instalira se s pip install brevo-python. Za nekoliko krajnjih točaka možete pozvati HTTP izravno:

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

Uspješno ažuriranje može vratiti prazan odgovor 204. None tada znači da za ID trebate ponovno pročitati kontakt.

Primjer pretpostavlja da je pozivatelj već provjerio privolu i blokade u Brevu. Ne traži uklanjanje blokade. Sa stvarnim ključem piše na račun; najprije ga ispitajte sa simulacijom. Sukobi identifikatora mogu vratiti različite 4xx kodove. Pročitajte odgovor i uskladite ID-jeve umjesto da uvijek očekujete 409.

Webhookovi

Webhookovi su način na koji saznajete što se dogodilo nakon slanja. POST /v3/webhooks stvara jedan, s poljima url, events, type i opcionalno channel (email ili sms), batched, prilagođenim headers i objektom auth.

Postoje tri vrste webhookova s različitim rječnicima događaja:

• Transakcijski: 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 zahtijevaju 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 promjene kontakata registrirajte marketinški webhook s contactUpdated. Brevo događaj u podacima naziva contact_updated. Primatelja potvrdite bearer tokenom auth ili vlastitim zaglavljima prema sigurnosnom vodiču. Tajnu provjerite prije obrade i ne zapisujte je u log.

Spremite ključ za uklanjanje duplikata iz vrste događaja, ID-ja kontakta i vremenske oznake na razdoblje ponovnih isporuka. Sama oznaka nije jedinstvena. Događaji se mogu ponoviti ili stići mimo redoslijeda. Poslije događaja ponovno pročitajte kontakt i uskladite ga s pouzdanim izvorom. Odredite prozor ponavljanja, nakon oporavka odbacite stare događaje i redovito provodite inkrementalnu provjeru. Webhook signalizira promjenu, sam ne stvara dvosmjernu sinkronizaciju. Vodič za poveznike opisuje izbor.

Ograničenja zahtjeva i rukovanje pogreškama

Ograničenja zahtjeva u platformi Brevo određuju se po krajnjoj točki i po razini plana, a raspon između krajnjih točaka je ogroman.

Brevo dokumentira x-sib-ratelimit-limit, x-sib-ratelimit-remaining i x-sib-ratelimit-reset na ograničenim krajnjim točkama. Čitajte ih i nakon uspjeha. Pri 429 čekajte reset pa ponavljajte samo unutar fiksnog broja pokušaja i vremena. Reset je trajanje u jedinici prozora, obično u sekundama, ne Unix vrijeme.

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. Sljedeći pokušaj zakažite poslije.

Pomoćna funkcija služi samo zahtjevima čije ste ponavljanje provjerili kao sigurno. Nakon nejasne pogreške slanja prvo uskladite ID poruke. Zapisujte status i zaglavlja, ne API ključ ili podatke kontakata.

Ne ponavljajte 4xx naslijepo. Referenca za stvaranje kontakta navodi 400 i 425; sukob ne mora biti 409. Nakon 5xx pri pisanju provjerite je li promjena već provedena.

Testiranje bez slanja pošte

Transakcijskom slanju dodajte zaglavlje X-Sib-Sandbox s vrijednošću drop. Brevo provjerava zahtjev, vraća 201 s vrijednošću messageId, ne isporučuje ništa i ne zapisuje zapis o e-pošti.

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 što to dokazuje, a što ne. Sandbox način provjerava samo format zahtjeva. Ne govori ništa o autentifikaciji pošiljatelja, iscrtavanju predloška ili isporučivosti. Držite zaseban Brevo račun za integracijsko testiranje svega što dira kontakte ili CRM podatke, jer sandbox način pokriva slanje, a ne ostatak API-ja.

Provjerite prije sinkronizacije kontakata

• Odaberite stabilan ID izvora za ext_id i spremite vraćeni Brevo ID.
• Provjerite atribute prije zapisa. Brevo može zanemariti nepoznata ili pogrešno tipizirana polja; ponovno pročitajte testni kontakt.
• Koristite izričit popis i pouzdan dokaz privole. Preskočite blokirane i odjavljene.
• Odvojeno brojite prihvaćene, primijenjene, preskočene i neuspjele zapise. Kod 202 za serije ili objekte prvo znači samo prihvat.
• Marketinške webhookove koristite kao signale i zatim uskladite stanje. Potvrdite, uklonite duplikate i ograničite ponavljanje.
• Pratite zaglavlja ograničenja i stanite nakon nekoliko pokušaja.

Tajo sinkronizira trgovačke podatke s Brevom. Ako taj sloj gradite sami, vodič za Brevo poveznike uspoređuje putove i pogreške.