Brevo API: практическо ръководство за разработчици

Импортът на контакт може да върне 201 и все пак да е грешен: ID на източника е изгубен, избран е грешен списък или предишно отписване е пренебрегнато. Това са решения за данните, не HTTP подробности.

Ръководството първо показва работеща заявка към Brevo, после проверките за малка повторяема синхронизация.

Какво покрива Brevo API

Всичко живее под един хост и един път с версия. Документацията за разработчици групира повърхността в четири продуктови области:

• Съобщения: транзакционни имейли, SMS и WhatsApp, включително групови изпращания, планиране и активност на съобщенията.
• Маркетингова платформа: контакти, списъци, сегменти и имейл кампании.
• Електронна търговия: продукти, поръчки и проследяване на събития за клиентите.
• Разговори: чат приспособлението и програмното управление на разговори.

Тези области споделят един акаунт, една база от контакти и един API ключ. Това е удобно и понякога опасно: скрипт, писан срещу представата Ви за тестови данни, говори със същите контакти, до които изпращат кампаниите Ви.

Транзакционни спрямо маркетингови

Двете семейства се държат достатъчно различно, за да е тяхното смесване най-честата проектантска грешка.

Ако още преценявате дали Brevo изобщо е правилната платформа, прегледът на платформата покрива тази територия.

Удостоверяване и управление на ключове

Brevo използва обикновен API ключ в собствен хедър. Хедърът се казва api-key, а не Authorization, и няма префикс Bearer. Това обърква почти всеки, който първо е работил с друг API за съобщения.

OAuth може да използва Bearer токен за поддържани операции; обикновеният API ключ продължава да се изпраща в заглавката api-key.

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

Ключовете се генерират в приложението на Brevo, в настройките на акаунта, в раздела SMTP and API, на таба API keys. Дайте на всеки ключ описателно име, обвързано със системата, която го използва. Стойността на ключа се показва точно веднъж при генерирането, така че ако я загубите, генерирате нов ключ, вместо да възстановявате стария.

Няколко практични правила:

• Издавайте отделен ключ за всяка среда и всяка услуга. Отнемането на компрометиран ключ никога не бива да сваля три несвързани системи.
• Стандартните API ключове важат за целия акаунт. Третирайте всеки ключ като пълен достъп до контактите, изпращането и CRM данните.
• Brevo поддържа и OAuth 2.0 за приложения, които действат от името на други Brevo акаунти, описан заедно с потока с ключове в схемите за удостоверяване.
• MCP сървърът, използван от AI асистенти, приема отделен токен и наистина използва bearer хедър. Този токен се генерира в същия екран с API ключове, но не е взаимозаменяем с REST ключ.

Базов URL, версии и Вашият първи запис

Базовият URL е https://api.brevo.com/v3/. Версията е в пътя, а не в хедър, и v3 е текущото поколение. Всеки път в това ръководство е относителен спрямо тази база.

За първия запис на контакт използвайте тестов адрес под Ваш контрол, валиден ID на списък и стабилен ID на източника. Първо създайте атрибута FNAME в Brevo. С истински ключ примерът записва директно:

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

Заменете 42 с ID на тестовия списък. Прочетете контакта отново и проверете ID, име, списък и блокиране. Само 2xx не доказва желания резултат.

Крайните адреси, които наистина ще използвате

Контакти

POST /v3/contacts създава контакт. Тялото приема email, дефинирани attributes, listIds и ext_id като стабилен ключ на източника. updateEnabled: true обновява съществуващ контакт, а getId: true иска крайния ID. Brevo документира полетата. Използвайте същия ext_id всеки път и пазете връзката между ID на източника и ID на Brevo.

Преди запис определете коя система управлява всеки атрибут и кой списък получава контактите със съгласие. Посочете listIds изрично. Не задавайте emailBlacklisted: false при обикновено обновяване. Brevo предупреждава, че промяна на адреса на блокиран контакт премахва блокирането. Обработвайте я отделно. Проверявайте блокирания и отписвания преди добавяне към маркетингов списък. Между четенето и записа има кратък прозорец; строгите изисквания налагат последна проверка преди изпращане.

Четенето минава през GET /v3/contacts, който страницира с limit (по подразбиране 50, максимум 1000) и offset и поддържа modifiedSince и createdSince в UTC. Инкременталните синхронизации трябва да стъпват на modifiedSince, вместо да обхождат целия списък. Обърнете внимание, че параметърът filter поддържа само оператор за равенство, така че всичко по-изразително е работа за сегмент.

За групово зареждане POST /v3/contacts/import приема fileUrl, fileBody или jsonBody, насочва се към listIds и работи асинхронно, връщайки processId. Brevo документира максимум 10 MB за тялото и препоръчва да останете близо до 8 MB, защото парсването раздува полезния товар. Подайте notifyUrl, за да научите резултата, вместо да го чакате чрез повтарящи се проверки.

Транзакционни имейли

POST /v3/smtp/email е работният кон. Освен sender, to, subject и htmlContent, полетата, които си струва да познавате, са:

• templateId заедно с params, което заменя вградено съдържание с шаблон на Brevo и неговите заместващи променливи. Параметрите на отделна версия са ограничени до 100 KB, а натрупаните параметри до 1000 KB.
• messageVersions, което изпраща персонализирани варианти с една заявка, до 99 получатели на версия.
• tags могат да помогнат да свържете събитията за доставка с процеса в приложението, който ги е предизвикал.
• scheduledAt заедно с batchId, за бъдещи изпращания, които може да искате да отмените наведнъж.
• headers, изписани с главни букви в началото на всяка дума, за персонализирани SMTP хедъри.

Една заявка приема най-много 2000 получатели. За разликата между този краен адрес и изпращането на кампании ръководството за транзакционни имейли дава гледната точка на стратегията за съобщения.

Имейл кампании

POST /v3/emailCampaigns изисква name и sender, плюс точно един източник на съдържание: htmlContent (минимум 10 знака, под 1 MB), htmlUrl или templateId. Аудиторията отива в recipients като listIds или segmentIds, а scheduledAt използва UTC формата YYYY-MM-DDTHH:mm:ss.SSSZ. Придружаващите маршрути покриват незабавно изпращане, изпращане на тест, промяна на статуса и извличане на отчета за кампанията.

Компании, сделки и обекти

CRM частта на Brevo има два припокриващи се пътя за запис и правилният избор има значение.

CRM маршрутите са POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} и еквивалентният набор за сделки. Те са синхронни. Един PATCH връща 204, щом промяната бъде приложена.

API за обекти е груповият път: POST /v3/objects/{object_type}/batch/upsert приема до 1000 записа и 1 MB на заявка, до 500 атрибута на запис и до 10 асоциирани записа на тип обект за запис. Връща 202 с processId, което означава прието, а не приложено.

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 покрива модела на обектите от гледна точка на оператора.

Официални SDK

Brevo поддържа клиенти в GitHub организацията getbrevo:

Node клиентът се инсталира като @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 клиентът се инсталира с pip install brevo-python. Ако предпочитате да не носите SDK зависимост заради два крайни адреса, чистата HTTP повърхност е достатъчно малка, за да я извикате директно, което Ви предпазва и от смяната на версии на SDK:

Python клиентът се инсталира с pip install brevo-python. За няколко крайни адреса можете да ползвате 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

Успешно обновяване може да върне празен отговор 204. None тогава значи, че трябва да прочетете контакта отново за неговия ID.

Примерът приема, че извикващият вече е проверил съгласието и блокиранията в Brevo. Не иска отблокиране. С истински ключ записва в акаунта; първо тествайте със симулация. Конфликтите на идентификатори могат да върнат различни кодове 4xx. Прочетете отговора и сверете ID, не приемайте винаги 409.

Webhooks

Webhooks са начинът, по който научавате какво се е случило след изпращане. POST /v3/webhooks създава такъв, с url, events, type и по избор channel (email или sms), batched, персонализирани headers и обект auth.

Има три вида webhooks с различен речник от събития:

• Транзакционни: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Маркетингови: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Входящи: inboundEmailProcessed и reply, които допълнително изискват 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"
  }'

За промени на контакти регистрирайте маркетингов webhook с contactUpdated. Brevo нарича събитието в данните contact_updated. Удостоверете получателя с bearer токена auth или собствени заглавки според ръководството за сигурност. Проверете тайната преди обработка и не я записвайте в логове.

Пазете ключ за премахване на дубликати от вид събитие, ID на контакта и времеви маркер за срок, покриващ повторните доставки. Самият маркер не е уникален. Събитията може да се повторят или да дойдат в различен ред. След събитие прочетете текущия контакт и го сверете с надеждния източник. Определете прозорец за повторно възпроизвеждане, отхвърляйте стари събития след възстановяване и правете редовни инкрементални проверки. Webhook сигнализира промяна, но сам не създава двупосочна синхронизация. Ръководството за конектори описва избора.

Ограничения на заявките и обработка на грешки

Ограниченията на Brevo са за всеки краен адрес и за всяко ниво на плана, а разликата между крайните адреси е огромна.

Brevo документира x-sib-ratelimit-limit, x-sib-ratelimit-remaining и x-sib-ratelimit-reset за ограничените крайни адреси. Четете ги и при успех. При 429 изчакайте нулиране и повтаряйте само в фиксирани граници за опити и време. Reset е продължителност в единицата на прозореца, обикновено секунди, не 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));
  }
}

Ако нужното изчакване надхвърля 60 секунди, функцията връща 429. Планирайте нов опит по-късно.

Помощната функция е само за заявки, за които сте проверили безопасността на повторение. След неясна грешка при изпращане първо сверете ID на съобщението. Записвайте статус и лимити, но никога API ключа или данни за контакти.

Не повтаряйте 4xx на сляпо. Справката за създаване посочва 400 и 425; конфликтът не е задължително 409. След 5xx при запис проверете дали промяната вече е приложена.

Тестване без изпращане на поща

Добавете хедъра X-Sib-Sandbox със стойност drop към транзакционно изпращане. Brevo валидира заявката, връща 201 с messageId, не доставя нищо и не записва имейл лог.

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

Разберете какво доказва и какво не доказва това. Пясъчният режим валидира само формата на заявката. Той не казва нищо за удостоверяването на изпращача, за визуализирането на шаблоните или за доставимостта. Пазете отделен Brevo акаунт за интеграционно тестване на всичко, което докосва контакти или CRM данни, защото пясъчният режим покрива изпращането, а не останалата част от API.

Проверете преди синхронизация на контакти

• Изберете стабилен ID на източника за ext_id и пазете върнатия Brevo ID.
• Проверете атрибутите преди запис. Brevo може да пропусне непознати или грешно типизирани полета; прочетете тестов контакт отново.
• Използвайте конкретен списък и надежден документ за съгласие. Пропуснете блокирани и отписани.
• Бройте отделно приети, приложени, пропуснати и неуспели записи. Код 202 за групи или обекти означава първо само приемане.
• Ползвайте маркетингови webhooks като сигнали и сверявайте текущото състояние. Удостоверявайте, премахвайте дубликати и ограничавайте възпроизвеждането.
• Следете заглавките за лимити и спирайте след няколко опита.

Tajo синхронизира търговски данни с Brevo. Ако изграждате този слой сами, ръководството за конектори Brevo сравнява пътищата и грешките.