Brevo API: gyakorlati fejlesztői útmutató

A kapcsolat létrehozása 201-et adhat, mégis hibás lehet az eredmény: elveszett a forrásazonosító, rossz listát választottál, vagy figyelmen kívül maradt egy leiratkozás. Ezek adatkezelési döntések, nem puszta HTTP-részletek.

Az útmutató először egy kapcsolatírást, majd egy kicsi, ismételhető szinkron ellenőrzéseit mutatja be.

Mit fed le a Brevo API

Minden egyetlen hoszt és egyetlen verzióútvonal alatt él. A fejlesztői dokumentáció négy termékterületre bontja a felületet:

• Üzenetküldés: tranzakciós e-mail, SMS és WhatsApp, beleértve a kötegelt küldést, az időzítést és az üzenetaktivitást.
• Marketingplatform: kapcsolatok, listák, szegmensek és e-mail kampányok.
• E-kereskedelem: termékek, rendelések és vásárlói eseménykövetés.
• Beszélgetések: a chatwidget és a programozott beszélgetéskezelés.

Ezek a területek egy fiókon, egy kapcsolati adatbázison és egy API-kulcson osztoznak. Ez kényelmes, és időnként veszélyes is: egy teszt gondolatmenettel megírt szkript ugyanazokkal a kapcsolatokkal beszélget, amelyeknek a kampányaid küldenek.

Tranzakciós kontra marketing

A két család elég eltérően viselkedik ahhoz, hogy az összekeverésük legyen a leggyakoribb tervezési hiba.

Ha még azt mérlegeled, hogy a Brevo egyáltalán a megfelelő platform-e, a platform áttekintése lefedi ezt a terepet.

Hitelesítés és kulcskezelés

A Brevo egy egyszerű API-kulcsot használ egyedi fejlécben. A fejléc neve api-key, nem Authorization, és nincs Bearer előtag. Ez szinte mindenkit megzavar, aki előbb valamelyik másik üzenetküldő API-t használta.

Az OAuth a támogatott műveleteknél Bearer tokent használhat; a szokásos API-kulcs továbbra is az api-key fejlécbe kerül.

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

A kulcsokat a Brevo alkalmazásban hozod létre, a fiókbeállítások alatt, az SMTP and API részben, az API keys fülön. Minden kulcsnak adj beszédes nevet, amely arra a rendszerre utal, amelyik használja. A kulcs értéke pontosan egyszer jelenik meg a létrehozáskor, így ha elveszíted, újat generálsz, nem pedig visszaszerzed a régit.

Néhány gyakorlati szabály:

• Adj ki külön kulcsot minden telepítési célkörnyezethez és minden szolgáltatáshoz. Egy kompromittált kulcs visszavonása soha ne állítson le három egymástól független rendszert.
• A szokásos API-kulcsok fiókszintűek. Minden kulcsot úgy kezelj, mint teljes hozzáférést a kapcsolatokhoz, a küldéshez és a CRM-adatokhoz.
• A Brevo OAuth 2.0-t is támogat azokhoz az alkalmazásokhoz, amelyek más Brevo-fiókok nevében járnak el, ezt a kulcsfolyamattal együtt írja le az authentication schemes oldal.
• Az MI-asszisztensek által használt MCP-szerver külön tokent vár, és az tényleg bearer fejlécet használ. Ez a token ugyanazon az API keys képernyőn készül, de nem cserélhető fel egy REST-kulccsal.

Alap-URL, verziózás és az első írás

Az alap-URL a https://api.brevo.com/v3/. A verzió az útvonalban van, nem fejlécben, és a v3 a jelenlegi generáció. Ebben az útmutatóban minden útvonal ehhez az alaphoz képest értendő.

Az első kapcsolatíráshoz használj saját tesztcímet, létező listaazonosítót és stabil forrásazonosítót. Előbb hozd létre a FNAME attribútumot a Brevóban. Valódi kulccsal a példa közvetlenül ír:

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

Cseréld a 42 értéket saját tesztlistád ID-jére. Olvasd vissza a kapcsolatot, és ellenőrizd az ID-t, nevet, listát és tiltásokat. A 2xx önmagában nem bizonyítja a várt eredményt.

A végpontok, amelyeket tényleg használni fogsz

Kapcsolatok

A POST /v3/contacts kapcsolatot hoz létre. A törzs az email, a deklarált attributes, a listIds és a stabil forráskulcsként használt ext_id mezőt fogadja. Az updateEnabled: true meglévő kapcsolatot frissít, a getId: true pedig az azonosítót kéri vissza. A Brevo dokumentálja ezeket. Minden futásban ugyanazt az ext_id értéket használd, és tárold a két rendszer azonosítóinak kapcsolatát.

Írás előtt döntsd el, melyik rendszer kezeli az egyes attribútumokat, és melyik listára kerülhet a hozzájárulással rendelkező kapcsolat. A listIds legyen explicit. Szokásos upsertben ne küldj emailBlacklisted: false értéket. A Brevo figyelmeztet: egy blokkolt kapcsolat e-mail címének módosítása feloldhatja a blokkolást. Kezeld külön a címmódosítást. Marketinglistára felvétel előtt ellenőrizd a tiltásokat és leiratkozásokat; az olvasás és írás közti versenyhelyzet miatt szigorú követelmény esetén küldés előtt újra ellenőrizz.

Az olvasás a GET /v3/contacts végponton megy, amely a limit (alapértelmezetten 50, legfeljebb 1000) és az offset paraméterrel lapoz, valamint támogatja a modifiedSince és a createdSince értéket UTC-ben. Az inkrementális szinkronizálás támaszkodjon a modifiedSince értékre a teljes lista végigjárása helyett. Vedd figyelembe, hogy a filter paraméter csak egyenlőségoperátort támogat, így minden ennél kifejezőbb dolog a szegmensekbe tartozik.

Tömeges betöltéshez a POST /v3/contacts/import elfogadja a fileUrl, fileBody vagy jsonBody mezőt, a listIds értéket célozza, aszinkron fut, és processId értéket ad vissza. A Brevo 10 MB-os maximális törzsméretet dokumentál, és azt ajánlja, hogy maradj 8 MB közelében, mert a feldolgozás felfújja a hasznos terhet. Add meg a notifyUrl értéket, hogy értesülj az eredményről lekérdezgetés helyett.

Tranzakciós e-mail

A POST /v3/smtp/email az igásló. A sender, to, subject és htmlContent mezőkön túl ezeket érdemes ismerned:

• templateId a params mezővel, amely a beágyazott tartalmat egy Brevo-sablonra és annak változóbehelyettesítéseire cseréli. Az egyes verziók paraméterei 100 KB-ban, a paraméterek összesített mérete 1000 KB-ban van korlátozva.
• messageVersions, amely egy hívásban küld személyre szabott változatokat, verziónként legfeljebb 99 címzettnek.
• A tags segíthet összekapcsolni a kézbesítési eseményeket az azokat kiváltó alkalmazásfolyamattal.
• scheduledAt a batchId értékkel a jövőbeli küldésekhez, amelyeket esetleg csoportosan szeretnél visszavonni.
• headers Title-Case formában az egyedi SMTP-fejlécekhez.

Egyetlen kérés legfeljebb 2000 címzettet fogad el. A végpont és a kampányküldés közötti különbséghez a tranzakciós e-mail útmutató adja az üzenetküldési stratégia nézetét.

E-mail kampányok

A POST /v3/emailCampaigns megköveteli a name és sender mezőt, plusz pontosan egy tartalomforrást: htmlContent (legalább 10 karakter, 1 MB alatt), htmlUrl vagy templateId. A célközönség a recipients mezőbe kerül listIds vagy segmentIds formában, a scheduledAt pedig a YYYY-MM-DDTHH:mm:ss.SSSZ UTC-formátumot használja. A kiegészítő útvonalak lefedik az azonnali küldést, a tesztküldést, az állapotfrissítést és a kampányjelentés lekérését.

Cégek, üzletek és objektumok

A Brevo CRM-je két, egymást átfedő írási úttal rendelkezik, és nem mindegy, melyiket választod.

A CRM-útvonalak a POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} és az üzletek megfelelő készlete. Ezek szinkronok. Egy PATCH 204-et ad vissza, amint a módosítás életbe lépett.

Az objektum-API a tömeges út: a POST /v3/objects/{object_type}/batch/upsert legfeljebb 1000 rekordot és kérésenként 1 MB-ot fogad, rekordonként legfeljebb 500 attribútumot, és objektumtípusonként és rekordonként legfeljebb 10 kapcsolati rekordot. 202-t ad vissza egy processId értékkel, ami elfogadottat jelent, nem alkalmazottat.

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

A Brevo CRM útmutató az objektummodellt az üzemeltető szemszögéből mutatja be.

Hivatalos SDK-k

A Brevo a getbrevo GitHub-szervezet alatt tartja karban a klienseket:

A Node-kliens az @getbrevo/brevo néven települ:

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

A Python-kliens a pip install brevo-python paranccsal települ. Ha nem szeretnél két végpont kedvéért SDK-függőséget cipelni, a nyers HTTP-felület elég kicsi ahhoz, hogy közvetlenül hívd, ami egyben elszigetel az SDK-verziók kavargásától is:

A Python-klienst a pip install brevo-python paranccsal telepítheted. Néhány végponthoz közvetlen HTTP-hívás is elég:

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

A sikeres frissítés üres 204-es választ adhat. Ilyenkor a None azt jelenti, hogy az azonosítóért vissza kell olvasnod a kapcsolatot.

A példa feltételezi, hogy a hívó már ellenőrizte a hozzájárulást és a Brevo tiltásait. Nem kér feloldást. Valódi kulccsal ír a fiókba; előbb próbáld ki mock válaszokkal. Azonosítóütközésre többféle 4xx válasz jöhet. Olvasd el a választ és egyeztesd az azonosítókat, ne feltételezd a 409-et.

Webhookok

A webhookokból tudod meg, mi történt egy küldés után. A POST /v3/webhooks létrehoz egyet, url, events, type mezőkkel, valamint opcionálisan a channel (email vagy sms), a batched, az egyedi headers és egy auth objektum megadásával.

Három webhooktípus létezik, eltérő eseményszókinccsel:

• Tranzakciós: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Marketing: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Bejövő: inboundEmailProcessed és reply, amelyekhez ráadásul kell egy domain érték is.

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

Kapcsolatváltozásokhoz marketing webhookot regisztrálj contactUpdated eseménnyel. A Brevo payloadban contact_updated néven szerepel. A fogadót a biztonsági útmutató szerinti auth bearer tokennel vagy egyéni fejléccel hitelesítsd. Feldolgozás előtt ellenőrizd a titkot, és ne naplózd.

Az eseménytípusból, kapcsolat-ID-ből és időbélyegből képzett deduplikációs kulcsot őrizd a kézbesítésismétlési ablak végéig. Az időbélyeg önmagában nem egyedi. Az események ismétlődhetnek vagy felcserélődhetnek. Ezért olvasd vissza az aktuális kapcsolatot, egyeztesd a megbízható forrással, korlátozd a visszajátszást, és helyreállítás után utasítsd el a régi eseményeket. Rendszeres inkrementális egyeztetés pótolja a kimaradt jelzéseket. A webhook önmagában nem kétirányú szinkron. A csatlakozó útmutató segít a választásban.

Sebességkorlátok és hibakezelés

A Brevo sebességkorlátai végpontonként és csomagszintenként érvényesek, és a végpontok közötti szórás óriási.

A Brevo a korlátozott végpontokhoz x-sib-ratelimit-limit, x-sib-ratelimit-remaining és x-sib-ratelimit-reset fejléceket dokumentál. Sikeres válasznál is olvasd őket. A 429 után várd meg a resetet, és csak rögzített próbálkozási és időkereten belül ismételj. A reset a korlátablak egységében megadott időtartam, rendszerint másodperc, nem Unix-idő.

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

Ha a szükséges várakozás több mint 60 másodperc, a függvény 429-et ad vissza. Későbbre időzíts újabb próbát.

A segédfüggvény csak olyan kérésekhez való, amelyek biztonságos ismétlését ellenőrizted. Bizonytalan küldési hiba után előbb egyeztesd a saját üzenetazonosítódat. A státuszt és korlátfejléceket naplózd, a kulcsot és kapcsolatadatokat ne.

Ne próbálj újra minden 4xx hibát. A kapcsolat létrehozásának referenciája 400-at és 425-öt sorol; ütközésnél nem garantált a 409. Írás utáni 5xx esetén előbb ellenőrizd, megtörtént-e az írás.

Tesztelés levélküldés nélkül

Add hozzá az X-Sib-Sandbox fejlécet drop értékkel egy tranzakciós küldéshez. A Brevo ellenőrzi a kérést, 201-et ad vissza egy messageId értékkel, semmit nem kézbesít, és nem ír e-mail naplóbejegyzést.

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

Értsd meg, mit bizonyít ez, és mit nem. A sandbox mód kizárólag a kérés formátumát validálja. Semmit nem mond a feladó hitelesítéséről, a sablonok megjelenítéséről vagy a kézbesíthetőségről. Tarts fenn külön Brevo-fiókot mindannak az integrációs teszteléséhez, ami kapcsolatokhoz vagy CRM-adatokhoz nyúl, mert a sandbox mód a küldést fedi le, az API többi részét nem.

Ellenőrzés kapcsolatszinkron előtt

• Válassz stabil forrás-ID-t az ext_id értékének, és tárold a Brevo ID-t.
• Írás előtt deklaráld az attribútumokat, majd olvasd vissza a tesztkapcsolatot.
• Használj konkrét listát és igazolható hozzájárulást; hagyd ki a tiltott és leiratkozott címeket.
• Külön számold az elfogadott, alkalmazott, kihagyott és sikertelen írásokat. A 202 első körben csak elfogadást jelent.
• A marketing webhookokat hitelesítsd, deduplikáld, és egyeztesd a tényleges állapottal.
• Figyeld a sebességkorlát-fejléceket, és korlátozd az újrapróbálást.

A Tajo kereskedelmi adatokat szinkronizál Brevóval. Ha magad építed ezt a réteget, a Brevo-csatlakozók útmutatója összehasonlítja a lehetőségeket.