Brevo API: en praktisk guide for utviklere

En kontaktimport kan gi 201 og likevel være feil: kilde-ID ble borte, feil liste ble valgt eller en tidligere avmelding ble oversett. Dette er beslutninger om data, ikke HTTP-detaljer.

Guiden får først et Brevo-kall til å virke, og viser deretter kontrollene for en liten, gjentakbar kontaktsynk.

Hva Brevo API dekker

Alt ligger under én host og én versjonssti. Utviklerdokumentasjonen grupperer flaten i fire produktområder:

• Meldinger: transaksjonell e-post, SMS og WhatsApp, inkludert batch-sendinger, planlegging og meldingsaktivitet.
• Markedsføringsplattform: kontakter, lister, segmenter og e-postkampanjer.
• eHandel: produkter, ordrer og sporing av kundehendelser.
• Samtaler: chat-widgeten og programmatisk håndtering av samtaler.

Disse områdene deler én konto, én kontaktdatabase og én API-nøkkel. Det er praktisk og av og til farlig: et skript skrevet mot en tenkt testversjon av dataene snakker med de samme kontaktene som kampanjene dine sender til.

Transaksjonell mot markedsføring

De to familiene oppfører seg ulikt nok til at det å blande dem er den vanligste designfeilen.

Er du fortsatt usikker på om Brevo er riktig plattform i det hele tatt, dekker plattformoversikten det terrenget.

Autentisering og nøkkelhåndtering

Brevo bruker en ren API-nøkkel i en egendefinert header. Headeren heter api-key, ikke Authorization, og det finnes ingen Bearer-prefiks. Dette snubler nesten alle som har brukt et annet meldings-API først.

OAuth kan bruke Bearer-token for operasjoner som støtter det; en vanlig API-nøkkel skal fortsatt sendes i api-key.

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

Nøkler genereres i Brevo-appen under kontoinnstillinger, i seksjonen SMTP og API, på fanen API-nøkler. Gi hver nøkkel et beskrivende navn knyttet til systemet som bruker den. Nøkkelverdien vises nøyaktig én gang når den genereres, så mister du den, genererer du en ny i stedet for å hente frem den gamle.

Noen praktiske regler:

• Utsted en egen nøkkel per miljø og per tjeneste. Å trekke tilbake en kompromittert nøkkel skal aldri ta ned tre urelaterte systemer.
• Vanlige API-nøkler gjelder hele kontoen. Behandle enhver nøkkel som full tilgang til kontakter, sending og CRM-data.
• Brevo støtter også OAuth 2.0 for applikasjoner som handler på vegne av andre Brevo-kontoer, beskrevet sammen med nøkkelflyten i authentication schemes.
• MCP-serveren som brukes av AI-assistenter, tar et eget token og bruker faktisk en bearer-header. Det tokenet genereres i samme skjermbilde for API-nøkler, men kan ikke brukes om hverandre med en REST-nøkkel.

Base-URL, versjonering og din første skriving

Base-URL-en er https://api.brevo.com/v3/. Versjonen ligger i stien og ikke i en header, og v3 er dagens generasjon. Alle stier i denne guiden er relative til den basen.

For første kontaktskriving bruker du en testadresse du kontrollerer, en gyldig liste-ID og en stabil kilde-ID. Opprett attributtet FNAME i Brevo først. Med en ekte nøkkel skriver dette eksemplet direkte:

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

Bytt 42 til ID-en til testlisten. Les kontakten tilbake og sjekk ID, navn, liste og sperrer. Bare 2xx beviser ikke ønsket synk.

Endepunktene du faktisk kommer til å bruke

Kontakter

POST /v3/contacts oppretter en kontakt. Forespørselen tar email, deklarerte attributes, listIds og ext_id som stabil kildenøkkel. updateEnabled: true oppdaterer en eksisterende kontakt, mens getId: true ber om slutt-ID. Brevo dokumenterer feltene. Bruk samme ext_id hver gang og lagre koblingen mellom kilde-ID og Brevo-ID.

Bestem før skriving hvilket system som eier hvert attributt og hvilken liste som mottar kontakter med samtykke. Oppgi listIds eksplisitt. Sett aldri emailBlacklisted: false i vanlige oppdateringer. Brevo advarer om at adresseendring for en sperret kontakt fjerner sperren. Behandle slike endringer separat. Sjekk sperrer og avmeldinger før kontakt legges til en markedsføringsliste. Mellom lesing og skriving finnes et kort tidsvindu; strenge krav trenger en siste kontroll før utsending.

Lesing går gjennom GET /v3/contacts, som pagineres med limit (standard 50, maksimum 1000) og offset, og støtter modifiedSince og createdSince i UTC. Inkrementelle synkroniseringer bør lene seg på modifiedSince i stedet for å gå gjennom hele listen. Merk at parameteren filter bare støtter en likhetsoperator, så alt mer uttrykksfullt hører hjemme i et segment.

For masseinnlasting tar POST /v3/contacts/import imot fileUrl, fileBody eller jsonBody, retter seg mot listIds og kjører asynkront med en processId i svaret. Brevo dokumenterer en grense på 10 MB kropp og anbefaler å holde seg nær 8 MB, fordi parsingen blåser opp nyttelasten. Oppgi notifyUrl slik at du får vite resultatet i stedet for å polle.

Transaksjonell e-post

POST /v3/smtp/email er arbeidshesten. Utover sender, to, subject og htmlContent er dette feltene som er verdt å kjenne:

• templateId med params, som erstatter inline innhold med en Brevo-mal og variabelinnsettingene den bruker. Enkeltversjoners params er begrenset til 100 KB, samlet params til 1000 KB.
• messageVersions, som sender personaliserte varianter i ett kall, med opptil 99 mottakere per versjon.
• tags kan hjelpe deg å knytte leveringshendelser til appflyten som skapte dem.
• scheduledAt sammen med batchId, for fremtidige sendinger du kanskje vil kansellere som gruppe.
• headers, i Title-Case, for egendefinerte SMTP-headere.

Én enkelt forespørsel tar imot maksimalt 2 000 mottakere. For forskjellen mellom dette endepunktet og kampanjesending har guiden til transaksjonell e-post det strategiske perspektivet.

E-postkampanjer

POST /v3/emailCampaigns krever name og sender, pluss nøyaktig én innholdskilde: htmlContent (minimum 10 tegn, under 1 MB), htmlUrl eller templateId. Målgruppen ligger i recipients som listIds eller segmentIds, og scheduledAt bruker UTC-formatet YYYY-MM-DDTHH:mm:ss.SSSZ. Tilhørende ruter dekker umiddelbar sending, testsending, statusoppdatering og uthenting av kampanjerapporten.

Bedrifter, deals og objekter

Brevos CRM har to overlappende skriveveier, og det å velge riktig betyr noe.

CRM-rutene er POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} og tilsvarende sett for deals. Disse er synkrone. En PATCH returnerer 204 så snart endringen er anvendt.

Objekt-API-et er masseveien: POST /v3/objects/{object_type}/batch/upsert tar opptil 1000 oppføringer og 1 MB per forespørsel, opptil 500 attributter per oppføring og opptil 10 assosiasjonsoppføringer per objekttype per oppføring. Det returnerer 202 med en processId, altså mottatt og ikke anvendt.

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

Brevo CRM-guiden dekker objektmodellen fra operatørens side.

Offisielle SDK-er

Brevo vedlikeholder klienter under GitHub-organisasjonen getbrevo:

Node-klienten installeres som @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-klienten installeres med pip install brevo-python. Vil du heller slippe en SDK-avhengighet for to endepunkter, er den rå HTTP-flaten liten nok til å kalle direkte, noe som også skjermer deg mot stadige SDK-versjoner:

Python-klienten installeres med pip install brevo-python. For få endepunkter kan du også kalle HTTP direkte:

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

En vellykket oppdatering kan gi et tomt 204-svar. None betyr da at du må lese kontakten igjen for å få ID-en.

Eksemplet forutsetter at den som kaller allerede har sjekket samtykke og sperrer i Brevo. Det ber ikke om oppheving av sperre. Med en ekte nøkkel skriver koden direkte; test først med simulerte svar. Identitetskonflikter kan gi ulike 4xx-koder. Les svaret og avstem ID-ene i stedet for å anta 409.

Webhooks

Webhooks er måten du får vite hva som skjedde etter en sending. POST /v3/webhooks oppretter én, med url, events, type og eventuelt channel (email eller sms), batched, egendefinerte headers og et auth-objekt.

Det finnes tre webhook-typer med hvert sitt hendelsesvokabular:

• Transaksjonell: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Markedsføring: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Innkommende: inboundEmailProcessed og reply, som i tillegg krever et 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"
  }'

For kontaktendringer registrerer du en markedsføringswebhook med contactUpdated. Brevo kaller hendelsen contact_updated i meldingen. Autentiser mottakeren med auth-bearertoken eller egne headere fra sikkerhetsguiden. Sjekk hemmeligheten før behandling, og ikke logg den.

Lagre en dedupliseringsnøkkel fra hendelsestype, kontakt-ID og tidsstempel lenge nok til å dekke nye leveranser. Tidsstempel alene er ikke unikt. Hendelser kan leveres flere ganger eller i feil rekkefølge. Les kontakten på nytt etter en hendelse og avstem mot autoritativ kilde. Definer et replay-vindu, avvis gamle hendelser etter gjenoppretting, og kjør regelmessige inkrementelle sjekker. En webhook signaliserer endring; alene gir den ikke toveis synk. Koblingsguiden forklarer valgene.

Rategrenser og feilhåndtering

Brevos rategrenser er satt per endepunkt og per plannivå, og spennet mellom endepunktene er enormt.

Brevo dokumenterer x-sib-ratelimit-limit, x-sib-ratelimit-remaining og x-sib-ratelimit-reset for begrensede endepunkter. Les dem også ved vellykket svar. Ved 429 venter du til reset og prøver bare igjen innen faste grenser for forsøk og tid. Resetverdien er en varighet i vinduets enhet, vanligvis sekunder, ikke Unix-tid.

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

Hvis nødvendig ventetid er over 60 sekunder, returnerer funksjonen 429. Planlegg et nytt forsøk senere.

Hjelpefunksjonen gjelder bare kall du har kontrollert kan gjentas trygt. Etter en uklar sendefeil må du avstemme meldings-ID før du sender på nytt. Logg status og rateheadere, aldri API-nøkkel eller kontaktdata.

Ikke gjenta 4xx ukritisk. Referansen for oppretting nevner 400 og 425; konflikt betyr ikke nødvendigvis 409. Etter 5xx ved skriving må du sjekke om endringen allerede er gjort.

Testing uten å sende e-post

Legg til headeren X-Sib-Sandbox med verdien drop på en transaksjonell sending. Brevo validerer forespørselen, returnerer 201 med en messageId, leverer ingenting og skriver ingen e-postlogg.

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

Forstå hva dette beviser og ikke beviser. Sandkassemodus validerer bare formatet på forespørselen. Den sier ingenting om avsenderautentisering, malgjengivelse eller leveringsevne. Ha en separat Brevo-konto for integrasjonstesting av alt som berører kontakter eller CRM-data, fordi sandkassemodus dekker sending og ikke resten av API-et.

Sjekk før kontaktsynk

• Velg en stabil kilde-ID for ext_id og lagre Brevo-ID-en som kommer tilbake.
• Kontroller attributter før skriving. Brevo kan ignorere ukjente eller feil typede felt; les en testkontakt tilbake.
• Bruk en bestemt liste og pålitelig dokumentasjon på samtykke. Hopp over sperrede og avmeldte kontakter.
• Tell mottatte, anvendte, hoppede og mislykkede poster hver for seg. 202 ved batch eller objekt betyr først bare mottatt.
• Bruk markedsføringswebhooks som signaler og avstem gjeldende tilstand. Autentiser, dedupliser og begrens replay.
• Følg med på rateheadere og stopp etter noen forsøk.

Tajo fokuserer på å synkronisere handelsdata med Brevo. Hvis du bygger dette selv, sammenligner Brevo-koblingsguiden veier og feilhåndtering.