Brevo API: Geliştiriciler İçin Pratik Bir Kılavuz

Kişi oluşturma 201 döndürebilir ama sonuç yine de yanlış olabilir: kaynak kimliği kaybolmuş, yanlış liste seçilmiş veya eski abonelikten çıkma göz ardı edilmiştir. Bunlar yalnızca HTTP ayrıntıları değil, veri kararlarıdır.

Bu rehber önce çalışan bir kişi yazma isteğini, ardından küçük ve tekrarlanabilir eşitleme için kontrolleri gösterir.

Brevo API neleri kapsar

Her şey tek bir sunucu ve tek bir sürüm yolu altında yer alır. Geliştirici dokümantasyonu yüzeyi dört ürün alanına ayırır:

• Mesajlaşma: toplu gönderimler, zamanlama ve mesaj etkinliği dahil olmak üzere işlemsel e-posta, SMS ve WhatsApp.
• Pazarlama platformu: kişiler, listeler, segmentler ve e-posta kampanyaları.
• eTicaret: ürünler, siparişler ve müşteri olayı takibi.
• Conversations: sohbet bileşeni ve programatik konuşma yönetimi.

Bu alanlar tek bir hesabı, tek bir kişi veritabanını ve tek bir API anahtarını paylaşır. Bu hem pratiktir hem de zaman zaman tehlikelidir: verinin hazırlık ortamındaki hâline göre yazılmış bir betik, kampanyalarınızın gönderim yaptığı aynı kişilerle konuşuyordur.

İşlemsel ile pazarlama arasındaki fark

İki aile, birbirine karıştırılması en yaygın tasarım hatası olacak kadar farklı davranır.

Brevo’nun sizin için doğru platform olup olmadığına hâlâ karar veriyorsanız, platform genel bakışı o konuyu ele alıyor.

Kimlik doğrulama ve anahtar yönetimi

Brevo, özel bir başlıkta düz bir API anahtarı kullanır. Başlığın adı Authorization değil api-key şeklindedir ve Bearer öneki yoktur. Bu durum, daha önce başka bir mesajlaşma API’si kullanmış olan hemen herkesin ayağını kaydırır.

OAuth, desteklenen işlemlerde Bearer belirteci kullanabilir; standart API anahtarı yine api-key üstbilgisine konur.

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

Anahtarlar Brevo uygulamasında hesap ayarları altında, SMTP ve API bölümünde, API anahtarları sekmesinde üretilir. Her anahtara, onu kullanan sisteme bağlı açıklayıcı bir ad verin. Anahtar değeri üretildiğinde tam olarak bir kez gösterilir, dolayısıyla kaybederseniz eskisini kurtarmak yerine yenisini üretirsiniz.

Birkaç pratik kural:

• Her dağıtım hedefi ve her servis için ayrı bir anahtar verin. Ele geçirilmiş bir anahtarı iptal etmek asla birbiriyle ilgisiz üç sistemi devre dışı bırakmamalıdır.
• Standart API anahtarları hesap genelindedir. Herhangi bir anahtarı kişilere, gönderime ve CRM verisine tam erişim olarak görün.
• Brevo ayrıca başka Brevo hesapları adına hareket eden uygulamalar için OAuth 2.0 destekler; bu, anahtar akışının yanında kimlik doğrulama şemalarında anlatılır.
• AI asistanlarının kullandığı MCP sunucusu ayrı bir token alır ve bearer başlığı kullanır. Bu token aynı API anahtarları ekranında üretilir ama bir REST anahtarıyla birbirinin yerine geçmez.

Temel URL, sürümleme ve ilk yazma işleminiz

Temel URL https://api.brevo.com/v3/ adresidir. Sürüm bir başlıkta değil yolda yer alır ve güncel nesil v3’tür. Bu kılavuzdaki her yol o temele görecelidir.

İlk kişi yazma işlemi için denetlediğiniz bir test adresi, geçerli liste kimliği ve kararlı kaynak kimliği kullanın. Önce Brevo içinde FNAME alanını oluşturun. Gerçek anahtarla bu örnek doğrudan yazar:

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 değerini test listenizin kimliğiyle değiştirin. Kişiyi yeniden okuyup kimliği, adı, listeyi ve engelleri doğrulayın. Tek başına 2xx beklenen sonucu kanıtlamaz.

Gerçekten kullanacağınız uç noktalar

Kişiler

POST /v3/contacts kişi oluşturur. Gövde email, tanımlı attributes, listIds ve kararlı kaynak anahtarı olarak ext_id alır. updateEnabled: true mevcut kişiyi günceller; getId: true son kimliği ister. Brevo bu alanları belgeler. Her çalıştırmada aynı ext_id değerini kullanın ve kaynak ile Brevo kimliklerinin eşleşmesini saklayın.

Yazmadan önce her alanın sahibi olan sistemi ve izinli kişilerin gideceği listeyi belirleyin. listIds değerini açıkça verin. Normal upsert işleminde emailBlacklisted: false göndermeyin. Brevo uyarır: engelli bir kişinin e-posta adresini değiştirmek engeli kaldırabilir. Adres değişimini ayrı yönetin. Pazarlama listesine eklemeden önce engelleri ve abonelikten çıkmaları kontrol edin. Okuma ile yazma arasında kısa bir yarış penceresi vardır; katı güvence için göndermeden hemen önce yeniden kontrol edin.

Okuma işlemleri GET /v3/contacts üzerinden yapılır; bu uç nokta limit (varsayılan 50, en fazla 1000) ve offset ile sayfalar, ayrıca UTC olarak modifiedSince ve createdSince destekler. Artımlı senkronizasyonlar tüm listeyi taramak yerine modifiedSince üzerine yaslanmalıdır. filter parametresinin yalnızca eşitlik operatörünü desteklediğini unutmayın, dolayısıyla daha ifadeli her şey bir segmentin işidir.

Toplu yükleme için POST /v3/contacts/import uç noktası fileUrl, fileBody veya jsonBody kabul eder, listIds hedefler ve eşzamansız çalışarak bir processId döndürür. Brevo 10 MB’lık bir gövde üst sınırı belgeler ve ayrıştırma yükü şişirdiği için 8 MB civarında kalmayı önerir. Sonucu yoklama yaparak değil öğrenerek almak için notifyUrl sağlayın.

İşlemsel e-posta

POST /v3/smtp/email asıl iş yükünü taşır. sender, to, subject ve htmlContent alanlarının ötesinde bilinmeye değer alanlar şunlardır:

• params ile birlikte templateId, satır içi içeriği bir Brevo şablonu ve değişken ikameleriyle değiştirir. Tekil sürüm parametreleri 100 KB, kümülatif parametreler 1000 KB ile sınırlıdır.
• messageVersions, kişiselleştirilmiş varyantları tek çağrıda gönderir, sürüm başına en fazla 99 alıcıyla.
• tags, teslimat olaylarını bunları üreten uygulama akışıyla ilişkilendirmeye yardımcı olabilir.
• scheduledAt ile batchId, grup olarak iptal etmek isteyebileceğiniz ileri tarihli gönderimler için.
• headers, özel SMTP başlıkları için Title-Case biçiminde.

Tek bir istek en fazla 2.000 alıcı kabul eder. Bu uç nokta ile kampanya gönderimi arasındaki farka mesajlaşma stratejisi açısından bakmak için işlemsel e-posta kılavuzu uygun kaynaktır.

E-posta kampanyaları

POST /v3/emailCampaigns uç noktası name ve sender alanlarını, ayrıca tam olarak bir içerik kaynağını gerektirir: htmlContent (en az 10 karakter, 1 MB altında), htmlUrl veya templateId. Hedef kitle recipients içinde listIds veya segmentIds olarak verilir ve scheduledAt alanı YYYY-MM-DDTHH:mm:ss.SSSZ UTC biçimini kullanır. Tamamlayıcı rotalar anında gönderim, test gönderimi, durum güncelleme ve kampanya raporunu çekme işlemlerini kapsar.

Şirketler, anlaşmalar ve nesneler

Brevo’nun CRM’inde birbiriyle örtüşen iki yazma yolu vardır ve doğru olanı seçmek önemlidir.

CRM rotaları POST /v3/companies, PATCH /v3/companies/{id}, DELETE /v3/companies/{id} ve anlaşmalar için eşdeğer kümedir. Bunlar eşzamanlıdır. Bir PATCH, değişiklik uygulandığında 204 döndürür.

Nesneler API’si toplu yoldur: POST /v3/objects/{object_type}/batch/upsert istek başına en fazla 1000 kayıt ve 1 MB, kayıt başına en fazla 500 öznitelik ve kayıt başına nesne türü başına en fazla 10 ilişki kaydı alır. Uygulandı değil kabul edildi anlamına gelen, processId içeren 202 döndürür.

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 kılavuzu nesne modelini operatör tarafından ele alıyor.

Resmi SDK’lar

Brevo, istemcileri getbrevo GitHub organizasyonu altında sürdürür:

Node istemcisi @getbrevo/brevo olarak kurulur:

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 istemcisi pip install brevo-python ile kurulur. İki uç nokta için bir SDK bağımlılığı taşımak istemiyorsanız, ham HTTP yüzeyi doğrudan çağrılabilecek kadar küçüktür ve bu sizi SDK sürüm dalgalanmalarından da korur:

Python istemcisini pip install brevo-python ile yükleyebilirsiniz. Birkaç uç nokta için doğrudan HTTP yeterlidir:

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

Başarılı güncelleme boş bir 204 yanıtı döndürebilir. Bu durumda None, kimlik için kişiyi yeniden okumanız gerektiği anlamına gelir.

Örnek, çağıranın izin ve Brevo engellerini önceden kontrol ettiğini varsayar. Engel kaldırmaz. Gerçek anahtar hesaba yazar; önce sahte yanıtlarla sınayın. Kimlik çakışmaları farklı 4xx kodları döndürebilir. Yanıtı okuyup kimlikleri uzlaştırın; her zaman 409 beklemeyin.

Webhook’lar

Webhook’lar, bir gönderimden sonra ne olduğunu öğrenme biçiminizdir. POST /v3/webhooks bir tane oluşturur; url, events, type ve isteğe bağlı olarak channel (email veya sms), batched, özel headers ve bir auth nesnesi alır.

Farklı olay sözlüklerine sahip üç webhook türü vardır:

• İşlemsel: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Pazarlama: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Gelen: ek olarak bir domain gerektiren inboundEmailProcessed ve reply.

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

Kişi değişiklikleri için contactUpdated içeren pazarlama webhooku kaydedin. Brevo yükteki olayı contact_updated diye adlandırır. Alıcıyı güvenlik rehberine göre auth bearer belirteci veya özel üstbilgiyle doğrulayın. Sırrı işlemeden önce kontrol edin ve günlüğe yazmayın.

Olay türü, kişi kimliği ve zaman damgasından bir tekilleştirme anahtarı üretip yeniden teslim penceresi boyunca saklayın. Yalnızca zaman damgası benzersiz değildir. Olaylar tekrar edebilir veya sırasız gelebilir. Güncel kişiyi yeniden okuyup güvenilir kaynakla mutabık kalın. Yeniden oynatma penceresini sınırlayın, kurtarma sonrası eski olayları reddedin ve kaçanları düzenli artımlı kontrollerle tamamlayın. Webhook tek başına çift yönlü eşitleme sağlamaz. Bağlayıcı rehberi seçenekleri anlatır.

Hız limitleri ve hata yönetimi

Brevo’nun hız limitleri uç nokta ve plan katmanı başınadır ve uç noktalar arasındaki fark devasadır.

Brevo, sınırlı uç noktalarda x-sib-ratelimit-limit, x-sib-ratelimit-remaining ve x-sib-ratelimit-reset üstbilgilerini belgeler. Başarılı yanıtta da okuyun. 429 sonrası sıfırlamayı bekleyin; yalnızca sabit deneme ve süre bütçesi içinde yeniden deneyin. Reset, pencere biriminde bir süredir, genellikle saniye; Unix zaman damgası değildir.

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

Gerekli bekleme 60 saniyeyi aşıyorsa işlev 429 döndürür. Sonraki denemeyi daha sonra zamanlayın.

Yardımcı işlev yalnızca tekrarının güvenli olduğunu doğruladığınız istekler içindir. Belirsiz gönderim hatasından sonra tekrar göndermeden kendi ileti kimliğinizle mutabakat yapın. Durumu ve limit üstbilgilerini kaydedin; anahtarı veya kişi verisini kaydetmeyin.

Tüm 4xx hatalarını körlemesine yinelemeyin. Kişi oluşturma referansı 400 ve 425 sayar; çakışma mutlaka 409 değildir. Yazma sonrası 5xx durumunda değişikliğin uygulanıp uygulanmadığını kontrol edin.

Posta göndermeden test etme

İşlemsel bir gönderime X-Sib-Sandbox başlığını drop değeriyle ekleyin. Brevo isteği doğrular, messageId ile 201 döndürür, hiçbir şey teslim etmez ve e-posta kaydı yazmaz.

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

Bunun neyi kanıtlayıp neyi kanıtlamadığını anlayın. Sandbox modu yalnızca istek biçimini doğrular. Gönderici kimlik doğrulaması, şablon işleme veya teslim edilebilirlik hakkında hiçbir şey söylemez. Kişilere veya CRM verisine dokunan her şeyin entegrasyon testi için ayrı bir Brevo hesabı tutun, çünkü sandbox modu gönderimi kapsar, API’nin geri kalanını değil.

Kişi eşitlemesi öncesi kontrol

• ext_id için kararlı kaynak kimliği seçin ve Brevo kimliğini saklayın.
• Alanları önce tanımlayın, test kişisini yazma sonrasında yeniden okuyun.
• Açık bir liste ve doğrulanabilir izin kullanın; engelli ve abonelikten çıkanları atlayın.
• Kabul edilen, uygulanan, atlanan ve başarısız kayıtları ayrı sayın. 202 ilk aşamada yalnızca kabul demektir.
• Pazarlama webhooklarını doğrulayıp tekilleştirin, sonra durumu mutabık kılın.
• Hız limiti üstbilgilerini izleyin ve sınırlı denemeden sonra durun.

Tajo ticaret verilerini Brevo ile eşitler. Bu katmanı kuruyorsanız Brevo bağlayıcı rehberine bakın.