Brevo API: ڈویلپرز کے لیے ایک عملی گائیڈ

کانٹیکٹ بناتے وقت 201 مل سکتا ہے مگر نتیجہ پھر بھی غلط ہو: سورس ID کھو جائے، غلط لسٹ منتخب ہو یا پرانی ان سبسکرائب حالت نظر انداز ہو۔ یہ ڈیٹا کے فیصلے ہیں، صرف HTTP کی تفصیل نہیں۔

گائیڈ پہلے کام کرنے والی کانٹیکٹ رائٹ دکھاتی ہے، پھر چھوٹے بار بار چلنے والے سنک کی جانچ بتاتی ہے۔

Brevo API کس چیز کا احاطہ کرتا ہے

سب کچھ ایک ہی ہوسٹ اور ایک ہی ورژن پاتھ کے نیچے موجود ہے۔ ڈویلپر دستاویزات اس سطح کو چار پروڈکٹ حصوں میں تقسیم کرتی ہیں:

• پیغام رسانی: ٹرانزیکشنل ای میل، SMS اور واٹس ایپ، بشمول بیچ سینڈز، شیڈولنگ اور پیغامات کی سرگرمی۔
• مارکیٹنگ پلیٹ فارم: رابطے، لسٹیں، سیگمنٹس اور ای میل مہمات۔
• eCommerce: پروڈکٹس، آرڈرز اور گاہک کے ایونٹ ٹریکنگ۔
• Conversations: چیٹ وجیٹ اور پروگرام کے ذریعے گفتگو کا انتظام۔

یہ حصے ایک ہی اکاؤنٹ، ایک ہی رابطہ ڈیٹابیس اور ایک ہی 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 اکاؤنٹس کی جانب سے عمل کرتی ہیں، جس کی وضاحت کی فلو کے ساتھ authentication schemes میں موجود ہے۔
• AI اسسٹنٹس کے استعمال کردہ MCP سرور ایک الگ ٹوکن لیتا ہے اور وہ bearer ہیڈر استعمال کرتا ہے۔ وہ ٹوکن اسی API keys اسکرین میں بنتا ہے لیکن REST کی کے ساتھ تبادلہ پذیر نہیں ہے۔

بیس URL، ورژننگ اور آپ کی پہلی رائٹ

بیس URL https://api.brevo.com/v3/ ہے۔ ورژن ہیڈر کے بجائے پاتھ میں ہے، اور v3 موجودہ نسل ہے۔ اس گائیڈ کا ہر پاتھ اسی بیس کے نسبت سے ہے۔

پہلی رائٹ کے لیے اپنے اختیار کا ٹیسٹ ای میل، درست لسٹ ID اور مستقل سورس ID استعمال کریں۔ پہلے Brevo میں FNAME ایٹریبیوٹ بنائیں۔ اصل کی کے ساتھ یہ مثال براہ راست لکھتی ہے:

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 اور Brevo ID کا ربط محفوظ رکھیں۔

لکھنے سے پہلے طے کریں کہ ہر ایٹریبیوٹ کس نظام کے ذمہ ہے اور رضامندی والے کانٹیکٹ کس لسٹ میں جائیں گے۔ listIds واضح دیں۔ عام اپ سرٹ میں emailBlacklisted: false نہ بھیجیں۔ Brevo خبردار کرتا ہے کہ بلاک کانٹیکٹ کا ای میل بدلنے سے بلاک ہٹ سکتا ہے۔ پتہ بدلنے کو الگ سنبھالیں۔ مارکیٹنگ لسٹ میں شامل کرنے سے پہلے بلاک اور ان سبسکرائب دیکھیں۔ پڑھنے اور لکھنے کے درمیان حالت بدل سکتی ہے؛ سخت ضمانت کے لیے بھیجنے سے فوراً پہلے پھر چیک کریں۔

ریڈز GET /v3/contacts سے گزرتی ہیں، جو limit (ڈیفالٹ 50، زیادہ سے زیادہ 1000) اور offset کے ساتھ صفحہ بندی کرتا ہے، اور UTC میں modifiedSince اور createdSince کی حمایت کرتا ہے۔ بتدریج سنک کو پوری فہرست چھاننے کے بجائے 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 ہیڈرز کے لیے۔

ایک ریکویسٹ زیادہ سے زیادہ 2,000 وصول کنندگان قبول کرتی ہے۔ اس اینڈ پوائنٹ اور مہم بھیجنے کے فرق کے لیے، ٹرانزیکشنل ای میل گائیڈ میں پیغام رسانی کی حکمت عملی کا نقطہ نظر موجود ہے۔

ای میل مہمات

POST /v3/emailCampaigns کو name اور sender درکار ہیں، اور اس کے ساتھ بالکل ایک مواد کا ذریعہ: htmlContent (کم از کم 10 حروف، 1 MB سے کم)، htmlUrl یا templateId۔ آڈیئنس recipients میں listIds یا segmentIds کے طور پر جاتی ہے، اور scheduledAt ‏YYYY-MM-DDTHH:mm:ss.SSSZ UTC فارمیٹ استعمال کرتا ہے۔ ساتھی روٹس فوری بھیجنے، ٹیسٹ بھیجنے، اسٹیٹس اپ ڈیٹ کرنے اور مہم کی رپورٹ نکالنے کا احاطہ کرتے ہیں۔

کمپنیاں، ڈیلز اور آبجیکٹس

Brevo کے CRM میں دو باہم متداخل رائٹ پاتھ ہیں، اور درست انتخاب اہمیت رکھتا ہے۔

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 ایسوسی ایشن ریکارڈز تک لیتا ہے۔ یہ processId کے ساتھ 202 واپس دیتا ہے، یعنی قبول کر لیا گیا، لاگو نہیں کیا گیا۔

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 گائیڈ آپریٹر کی طرف سے آبجیکٹ ماڈل کا احاطہ کرتی ہے۔

سرکاری SDKs

Brevo کلائنٹس کو getbrevo نامی GitHub تنظیم کے تحت برقرار رکھتا ہے:

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 بلاک پہلے چیک کر لیے ہیں۔ یہ بلاک نہیں ہٹاتی۔ اصل کی اکاؤنٹ میں لکھے گی؛ پہلے فرضی جوابات سے آزمائیں۔ ID ٹکراؤ مختلف 4xx دے سکتا ہے۔ جواب پڑھ کر ID ملائیں، ہمیشہ 409 نہ سمجھیں۔

ویب ہکس

ویب ہکس وہ ذریعہ ہیں جن سے آپ کو معلوم ہوتا ہے کہ سینڈ کے بعد کیا ہوا۔ POST /v3/webhooks ایک ویب ہک بناتا ہے، جس میں url، events، type، اور اختیاری طور پر channel (email یا sms)، batched، کسٹم headers اور ایک auth آبجیکٹ ہوتے ہیں۔

تین ویب ہک ٹائپس ہیں جن کے ایونٹ الفاظ الگ ہیں:

• ٹرانزیکشنل: 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"
  }'

کانٹیکٹ تبدیلی کے لیے contactUpdated والا مارکیٹنگ ویب ہک رجسٹر کریں۔ Brevo پے لوڈ میں ایونٹ کا نام contact_updated رکھتا ہے۔ سیکیورٹی گائیڈ کے مطابق auth bearer ٹوکن یا خاص ہیڈر سے وصولی کی تصدیق کریں۔ عمل سے پہلے راز چیک کریں اور لاگ میں نہ لکھیں۔

ایونٹ کی قسم، کانٹیکٹ ID اور وقت سے ڈپلیکیٹ ہٹانے کی کی بنائیں اور دوبارہ ڈیلیوری کی مدت تک رکھیں۔ صرف وقت منفرد نہیں۔ ایونٹ دہر سکتے ہیں یا ترتیب بدل سکتی ہے۔ موجودہ کانٹیکٹ دوبارہ پڑھ کر معتبر سورس سے ملائیں۔ ری پلے مدت محدود کریں، بحالی کے بعد پرانے ایونٹ رد کریں اور معمول کے انکریمنٹل چیک سے رہ جانے والے پکڑیں۔ ویب ہک اکیلا دو طرفہ سنک نہیں بناتا۔ کنیکٹر گائیڈ دیکھیں۔

ریٹ لمٹس اور خرابی کا انتظام

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 ملائیں۔ اسٹیٹس اور ریٹ ہیڈرز لاگ کریں، کی یا کانٹیکٹ ڈیٹا نہیں۔

ہر 4xx اندھا دھند نہ دہرائیں۔ کانٹیکٹ بنانے کی ریفرنس میں 400 اور 425 ہیں؛ ٹکراؤ لازماً 409 نہیں۔ رائٹ کے بعد 5xx آئے تو پہلے دیکھیں تبدیلی لگ تو نہیں گئی۔

میل بھیجے بغیر ٹیسٹنگ

ٹرانزیکشنل سینڈ میں X-Sib-Sandbox ہیڈر drop ویلیو کے ساتھ شامل کریں۔ Brevo ریکویسٹ کی توثیق کرتا ہے، messageId کے ساتھ 201 واپس دیتا ہے، کچھ ڈیلیور نہیں کرتا اور کوئی ای میل لاگ نہیں لکھتا۔

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

یہ سمجھ لیں کہ اس سے کیا ثابت ہوتا ہے اور کیا نہیں۔ سینڈ باکس موڈ صرف ریکویسٹ کے فارمیٹ کی توثیق کرتا ہے۔ یہ سینڈر کی تصدیق، ٹیمپلیٹ رینڈرنگ یا ڈیلیوریبلٹی کے بارے میں کچھ نہیں کہتا۔ رابطوں یا CRM ڈیٹا کو چھونے والی کسی بھی چیز کی انٹیگریشن ٹیسٹنگ کے لیے الگ Brevo اکاؤنٹ رکھیں، کیونکہ سینڈ باکس موڈ صرف بھیجنے کا احاطہ کرتا ہے، باقی API کا نہیں۔

کانٹیکٹ سنک سے پہلے جانچ

• ext_id کے لیے مستقل سورس ID منتخب کریں اور Brevo ID محفوظ کریں۔
• پہلے ایٹریبیوٹ بنائیں، پھر ٹیسٹ کانٹیکٹ دوبارہ پڑھیں۔
• واضح لسٹ اور معتبر رضامندی ثبوت رکھیں؛ بلاک اور ان سبسکرائب افراد چھوڑیں۔
• قبول، لاگو، چھوڑے اور ناکام رائٹس الگ گنیں۔ 202 ابتدا میں صرف قبول ہونا ہے۔
• مارکیٹنگ ویب ہکس کی تصدیق اور ڈپلیکیٹ صفائی کے بعد حالت ملائیں۔
• ریٹ ہیڈرز دیکھیں اور مقررہ کوششوں کے بعد رکیں۔

Tajo تجارت کا ڈیٹا Brevo سے سنک کرتا ہے۔ خود بنانے پر کنیکٹر گائیڈ دیکھیں۔