Brevo API: डेवलपर के लिए एक व्यावहारिक गाइड

कॉन्टैक्ट बनाने पर 201 मिल सकता है, लेकिन नतीजा फिर भी गलत हो: स्रोत ID खो जाए, गलत लिस्ट चुनी जाए या पहले की अनसब्सक्राइब स्थिति छूट जाए। ये डेटा के फैसले हैं, सिर्फ HTTP के विवरण नहीं।

यह गाइड पहले काम करने वाला कॉन्टैक्ट राइट दिखाती है, फिर छोटे, दोहराए जा सकने वाले सिंक की जांचें बताती है।

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 अकाउंट की ओर से काम करते हैं, जिसका वर्णन की फ़्लो के साथ ही authentication schemes में है.
• AI असिस्टेंट जो MCP सर्वर इस्तेमाल करते हैं, वह अलग टोकन लेता है और बियरर हेडर ही इस्तेमाल करता है. वह टोकन उसी 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 रखें और स्रोत तथा 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 टेम्पलेट और उसके वेरिएबल प्रतिस्थापन रख देता है. अलग-अलग वर्ज़न params 100 KB पर और कुल params 1000 KB पर सीमित हैं.
• messageVersions, जो एक ही कॉल में व्यक्तिगत बनाए गए वेरिएंट भेजता है, प्रति वर्ज़न 99 प्राप्तकर्ता तक.
• tags डिलीवरी इवेंट को उसे शुरू करने वाले ऐप वर्कफ़्लो से जोड़ने में मदद कर सकते हैं।
• scheduledAt के साथ batchId, उन भविष्य के सेंड के लिए जिन्हें आप समूह के रूप में कैंसल करना चाह सकते हैं.
• headers, Title-Case में, कस्टम 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 गाइड ऑब्जेक्ट मॉडल को ऑपरेटर के नज़रिए से कवर करती है.

आधिकारिक SDK

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 से सिंक करता है। खुद बनाने पर कनेक्टर गाइड देखें।