Brevo API: praktični vodnik za razvijalce

Uvoz stika lahko vrne 201 in je še vedno napačen: ID vira se je izgubil, izbran je napačen seznam ali pa je bila prezrta odjava. To so odločitve o podatkih, ne podrobnosti HTTP.

Vodnik najprej pokaže delujoč klic Brevo, nato preverjanja za majhno, ponovljivo sinhronizacijo.

Kaj pokriva Brevo API

Vse živi pod enim gostiteljem in eno potjo z različico. Razvijalska dokumentacija površino razdeli na štiri produktna področja:

• Sporočanje: transakcijska e-pošta, SMS in WhatsApp, vključno s paketnimi pošiljanji, načrtovanjem in aktivnostjo sporočil.
• Marketinška platforma: stiki, seznami, segmenti in e-poštne kampanje.
• E-trgovina: izdelki, naročila in sledenje dogodkom strank.
• Pogovori: klepetalni pripomoček in programsko upravljanje pogovorov.

Ta področja si delijo en račun, eno zbirko stikov in en ključ API. To je priročno in občasno nevarno: skripta, napisana za neko testno predstavo o podatkih, se pogovarja z istimi stiki, ki jim pošiljate kampanje.

Transakcijsko proti marketinškemu

Družini se vedeta dovolj različno, da je njuno mešanje najpogostejša napaka v zasnovi.

Če se šele odločate, ali je Brevo sploh prava platforma, ta teren pokriva pregled platforme.

Avtentikacija in upravljanje ključev

Brevo uporablja navaden ključ API v glavi po meri. Glava se imenuje api-key, ne Authorization, in nima predpone Bearer. To zmede skoraj vsakogar, ki je pred tem uporabljal kakšen drug API za sporočanje.

OAuth lahko za podprte postopke uporablja žeton Bearer; običajni ključ API še vedno sodi v glavo api-key.

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

Ključe ustvarite v aplikaciji Brevo v nastavitvah računa, v razdelku SMTP and API, na zavihku API keys. Vsakemu ključu dajte opisno ime, vezano na sistem, ki ga uporablja. Vrednost ključa je prikazana natanko enkrat ob ustvarjanju, zato ob izgubi ustvarite novega, starega pa ne morete obnoviti.

Nekaj praktičnih pravil:

• Izdajte ločen ključ za vsako ciljno okolje in vsako storitev. Preklic razkritega ključa ne sme nikoli podreti treh nepovezanih sistemov.
• Standardni ključi API veljajo za celoten račun. Vsak ključ obravnavajte kot poln dostop do stikov, pošiljanja in podatkov CRM.
• Brevo podpira tudi OAuth 2.0 za aplikacije, ki delujejo v imenu drugih računov Brevo, kar je skupaj s potekom za ključe opisano v shemah avtentikacije.
• Strežnik MCP, ki ga uporabljajo pomočniki AI, uporablja ločen žeton in res uporablja glavo bearer. Ta žeton nastane na istem zaslonu z API keys, vendar ni zamenljiv s ključem REST.

Osnovni URL, različice in vaš prvi zapis

Osnovni URL je https://api.brevo.com/v3/. Različica je v poti in ne v glavi, v3 pa je trenutna generacija. Vsaka pot v tem vodniku je relativna glede na to osnovo.

Za prvi zapis stika uporabite preizkusni naslov pod svojim nadzorom, veljaven ID seznama in stabilen ID vira. Najprej v Brevo ustvarite atribut FNAME. S pravim ključem primer piše neposredno v račun:

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

Zamenjajte 42 z ID preizkusnega seznama. Ponovno preberite stik in preverite ID, ime, seznam in blokade. Sam 2xx ne dokazuje pričakovanega rezultata.

Končne točke, ki jih boste dejansko uporabljali

Stiki

POST /v3/contacts ustvari stik. Telo sprejme email, deklarirane attributes, listIds in ext_id kot stabilen ključ vira. updateEnabled: true posodobi obstoječ stik, getId: true pa zahteva končni ID. Brevo dokumentira polja. Pri vsakem zagonu uporabite isti ext_id in shranite povezavo med ID vira in ID Brevo.

Pred zapisom določite, kateri sistem upravlja vsak atribut in kateri seznam sprejema stike s privolitvijo. listIds navedite izrecno. Pri običajnem upsertu nikoli ne nastavite emailBlacklisted: false. Brevo opozarja, da sprememba naslova blokiranega stika odstrani blokado. Obravnavajte jo posebej. Pred dodajanjem na trženjski seznam preverite blokade in odjave. Med branjem in pisanjem ostane kratek časovni interval; stroga pravila zahtevajo še zadnji pregled pred pošiljanjem.

Branja gredo prek GET /v3/contacts, ki straniči s parametroma limit (privzeto 50, največ 1000) in offset ter podpira modifiedSince in createdSince v UTC. Inkrementalne sinhronizacije naj se opirajo na modifiedSince in ne na sprehod čez celoten seznam. Upoštevajte, da parameter filter podpira samo operator enakosti, zato karkoli izraznejšega sodi v segment.

Za množično nalaganje POST /v3/contacts/import sprejme fileUrl, fileBody ali jsonBody, cilja na listIds in teče asinhrono ter vrne processId. Brevo dokumentira največ 10 MB telesa in priporoča, da ostanete blizu 8 MB, ker razčlenjevanje poveča vsebino. Nastavite notifyUrl, da izid izveste, namesto da poizvedujete.

Transakcijska e-pošta

POST /v3/smtp/email je delovni konj. Poleg sender, to, subject in htmlContent so vredna poznavanja tudi ta polja:

• templateId skupaj s params, ki vgrajeno vsebino zamenja s predlogo Brevo in njenimi zamenjavami spremenljivk. Parametri posamezne različice so omejeni na 100 KB, skupni parametri na 1000 KB.
• messageVersions, ki v enem klicu pošlje prilagojene različice, z največ 99 prejemniki na različico.
• tags lahko pomagajo povezati dogodke dostave s postopkom v aplikaciji, ki jih je sprožil.
• scheduledAt skupaj z batchId za prihodnja pošiljanja, ki jih boste morda želeli preklicati kot skupino.
• headers, zapisano v obliki Title-Case, za glave SMTP po meri.

Ena zahteva sprejme največ 2.000 prejemnikov. Za razliko med to končno točko in pošiljanjem kampanj ima vodnik po transakcijski e-pošti pogled s strani strategije sporočanja.

E-poštne kampanje

POST /v3/emailCampaigns zahteva name in sender ter natanko en vir vsebine: htmlContent (najmanj 10 znakov, pod 1 MB), htmlUrl ali templateId. Občinstvo gre v recipients kot listIds ali segmentIds, scheduledAt pa uporablja obliko UTC YYYY-MM-DDTHH:mm:ss.SSSZ. Spremljajoče poti pokrivajo takojšnje pošiljanje, pošiljanje preizkusa, posodabljanje stanja in pridobivanje poročila o kampanji.

Podjetja, posli in objekti

CRM v Brevu ima dve prekrivajoči se poti za zapisovanje in pravilna izbira šteje.

Poti CRM so POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} in enakovreden nabor za posle. Te so sinhrone. PATCH vrne 204, ko je sprememba uveljavljena.

API za objekte je pot za množične zapise: POST /v3/objects/{object_type}/batch/upsert sprejme do 1000 zapisov in 1 MB na zahtevo, do 500 atributov na zapis in do 10 povezanih zapisov na tip objekta na zapis. Vrne 202 z vrednostjo processId, kar pomeni sprejeto in ne uveljavljeno.

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

Vodnik po Brevo CRM pokriva objektni model z operativne strani.

Uradni SDK

Brevo vzdržuje odjemalce v organizaciji getbrevo na GitHubu:

Odjemalec za Node se namesti kot @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);

Odjemalec za Python se namesti z pip install brevo-python. Če za dve končni točki raje ne bi nosili odvisnosti od SDK, je surova površina HTTP dovolj majhna, da jo pokličete neposredno, kar vas hkrati zavaruje pred menjavami različic SDK:

Odjemalca Python namestite z pip install brevo-python. Za nekaj končnih točk lahko HTTP pokličete neposredno:

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šna posodobitev lahko vrne prazen odgovor 204. None pomeni, da morate za ID stik ponovno prebrati.

Primer predpostavlja, da je klicatelj že preveril privolitev in blokade v Brevo. Ne zahteva odblokiranja. S pravim ključem piše v račun; najprej ga preizkusite s simulacijo. Konflikti identifikatorjev lahko vrnejo različne kode 4xx. Preberite odgovor in uskladite ID, ne predpostavljajte vedno 409.

Webhooki

Webhooki so način, kako izveste, kaj se je zgodilo po pošiljanju. POST /v3/webhooks ustvari webhook s parametri url, events, type in po želji channel (email ali sms), batched, glavami po meri v headers in objektom auth.

Obstajajo tri vrste webhookov z različnimi besedišči dogodkov:

• 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.
• Vhodni: inboundEmailProcessed in reply, ki dodatno zahtevata 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 spremembe stikov registrirajte trženjski webhook s contactUpdated. Brevo dogodek v podatkih imenuje contact_updated. Prejemnika overite z žetonom bearer auth ali lastnimi glavami po varnostnem vodniku. Skrivnost preverite pred obdelavo in je ne beležite.

Shranite ključ za odstranjevanje dvojnikov iz vrste dogodka, ID stika in časovnega žiga za obdobje ponovnih dostav. Sam žig ni enoličen. Dogodki se lahko ponovijo ali pridejo v napačnem vrstnem redu. Po dogodku znova preberite stik in ga uskladite z avtoritativnim virom. Določite okno ponovnega predvajanja, po obnovi zavrnite stare dogodke in redno izvajajte inkrementalni pregled. Webhook signalizira spremembo; sam ne ustvari dvosmerne sinhronizacije. Vodnik za povezovalnike opisuje izbiro.

Omejitve zahtev in obravnava napak

Omejitve zahtev v Brevu veljajo za posamezno končno točko in raven paketa, razpon med končnimi točkami pa je ogromen.

Brevo dokumentira x-sib-ratelimit-limit, x-sib-ratelimit-remaining in x-sib-ratelimit-reset na omejenih končnih točkah. Berite jih tudi pri uspehu. Ob 429 počakajte na ponastavitev in ponavljajte samo v določenih mejah poskusov in časa. Reset je trajanje v enoti okna, običajno v sekundah, ne č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));
  }
}

Če je potrebno čakanje daljše od 60 sekund, funkcija vrne 429. Naslednji poskus načrtujte pozneje.

Ta pomočnik velja le za zahteve, pri katerih ste preverili varnost ponavljanja. Po nejasni napaki pošiljanja najprej uskladite ID sporočila. Beležite stanje in glave omejitev, nikoli ključa API ali podatkov stika.

Ne ponavljajte 4xx na slepo. Referenca za ustvarjanje stika navaja 400 in 425; konflikt ni nujno 409. Po 5xx pri zapisu preverite, ali se je sprememba že uveljavila.

Preizkušanje brez pošiljanja pošte

Transakcijskemu pošiljanju dodajte glavo X-Sib-Sandbox z vrednostjo drop. Brevo preveri zahtevo, vrne 201 z vrednostjo messageId, ne dostavi ničesar in ne zapiše nobenega dnevnika e-pošte.

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

Razumite, kaj to dokaže in česa ne. Peskovnik preveri samo obliko zahteve. O avtentikaciji pošiljatelja, izrisu predloge ali dostavljivosti ne pove nič. Za integracijsko preizkušanje česarkoli, kar se dotika stikov ali podatkov CRM, imejte ločen račun Brevo, saj peskovnik pokriva pošiljanje in ne preostanka vmesnika API.

Pred sinhronizacijo stikov

• Izberite stabilen ID vira za ext_id in shranite vrnjeni ID Brevo.
• Atribute preverite pred zapisom. Brevo lahko neznana ali napačno tipizirana polja prezre; ponovno preberite preizkusni stik.
• Uporabite jasen seznam in zanesljiv dokaz privolitve. Preskočite blokade in odjave.
• Ločeno štejte sprejete, uporabljene, preskočene in neuspešne zapise. Koda 202 za serije ali objekte sprva potrdi le sprejem.
• Trženjske webhooke uporabite kot signale in nato uskladite trenutno stanje. Overite, odstranite dvojnike in omejite ponovno predvajanje.
• Spremljajte glave omejitev in se ustavite po nekaj poskusih.

Tajo se osredotoča na sinhronizacijo trgovskih podatkov z Brevo. Če to plast gradite sami, vodnik za povezovalnike Brevo primerja poti in napake.