Brevo API: คู่มือเชิงปฏิบัติสำหรับนักพัฒนา

การสร้างผู้ติดต่ออาจได้ 201 แต่ผลยังผิด เช่น ID ต้นทางหาย เลือกรายการผิด หรือไม่สนใจการยกเลิกรับข่าวสารก่อนหน้า เรื่องเหล่านี้เป็นการตัดสินใจด้านข้อมูล ไม่ใช่เพียงรายละเอียด HTTP

คู่มือนี้เริ่มจากคำขอเขียนผู้ติดต่อที่ทำงานได้ แล้วอธิบายการตรวจสอบสำหรับการซิงค์ขนาดเล็กที่ทำซ้ำได้

Brevo API ครอบคลุมอะไรบ้าง

ทุกอย่างอยู่ภายใต้โฮสต์เดียวและ path เวอร์ชันเดียว เอกสารสำหรับนักพัฒนา จัดกลุ่มพื้นผิวนี้ออกเป็นสี่กลุ่มผลิตภัณฑ์

• การส่งข้อความ: อีเมลธุรกรรม SMS และ WhatsApp รวมถึงการส่งแบบกลุ่ม การตั้งเวลา และกิจกรรมของข้อความ
• แพลตฟอร์มการตลาด: ผู้ติดต่อ รายชื่อ เซกเมนต์ และแคมเปญอีเมล
• eCommerce: สินค้า ออเดอร์ และการติดตามอีเวนต์ของลูกค้า
• Conversations: วิดเจ็ตแชทและการจัดการบทสนทนาแบบเขียนโปรแกรม

กลุ่มเหล่านี้ใช้บัญชีเดียวกัน ฐานข้อมูลผู้ติดต่อเดียวกัน และ API key เดียวกัน ซึ่งสะดวกและบางครั้งก็อันตราย เพราะสคริปต์ที่เขียนขึ้นโดยคิดว่ากำลังคุยกับข้อมูลทดสอบ กำลังคุยกับผู้ติดต่อชุดเดียวกับที่แคมเปญของคุณส่งถึงจริง

ธุรกรรมกับการตลาด

สองตระกูลนี้ทำงานต่างกันมากพอที่การสับสนระหว่างกันจะเป็นข้อผิดพลาดด้านการออกแบบที่พบบ่อยที่สุด

หากคุณยังตัดสินใจไม่ได้ว่า Brevo เหมาะกับคุณหรือไม่ ภาพรวมแพลตฟอร์ม ครอบคลุมประเด็นนั้นไว้แล้ว

การยืนยันตัวตนและการจัดการคีย์

Brevo ใช้ API key แบบธรรมดาใน header ที่กำหนดเอง header นั้นชื่อ api-key ไม่ใช่ Authorization และไม่มีคำนำหน้า Bearer จุดนี้ทำให้เกือบทุกคนที่เคยใช้ API ส่งข้อความเจ้าอื่นมาก่อนสะดุด

OAuth อาจใช้ Bearer token กับการดำเนินการที่รองรับ ส่วนคีย์ API ปกติยังต้องใส่ในส่วนหัว api-key

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

คีย์สร้างได้ในแอป Brevo ที่หน้าการตั้งค่าบัญชี ในส่วน SMTP and API แท็บ API keys ตั้งชื่อคีย์แต่ละตัวให้สื่อถึงระบบที่ใช้งานมัน ค่าของคีย์จะแสดงเพียงครั้งเดียวตอนสร้าง ดังนั้นถ้าทำหาย คุณต้องสร้างใหม่แทนที่จะกู้ของเดิม

กฎเชิงปฏิบัติที่ควรจำ

• ออกคีย์แยกต่อสภาพแวดล้อมการติดตั้งและต่อบริการ การเพิกถอนคีย์ที่รั่วไหลไม่ควรทำให้ระบบที่ไม่เกี่ยวข้องกันสามระบบล่มไปด้วย
• API key มาตรฐานมีสิทธิ์ทั้งบัญชี ให้ถือว่าทุกคีย์เข้าถึงผู้ติดต่อ การส่ง และข้อมูล CRM ได้เต็มที่
• Brevo ยังรองรับ OAuth 2.0 สำหรับแอปพลิเคชันที่ทำงานแทนบัญชี Brevo อื่น ซึ่งอธิบายไว้คู่กับการใช้คีย์ใน authentication schemes
• เซิร์ฟเวอร์ MCP ที่ผู้ช่วย AI ใช้ ต้องใช้โทเค็นแยกต่างหากและใช้ header แบบ bearer จริง โทเค็นนั้นสร้างในหน้า API keys เดียวกันแต่ใช้แทน REST key ไม่ได้

Base URL การกำหนดเวอร์ชัน และการเขียนข้อมูลครั้งแรก

Base URL คือ https://api.brevo.com/v3/ เวอร์ชันอยู่ใน path ไม่ใช่ใน header และ v3 คือรุ่นปัจจุบัน ทุก path ในคู่มือนี้อ้างอิงจาก base นั้น

สำหรับการเขียนครั้งแรก ใช้อีเมลทดสอบที่คุณควบคุม 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 เพียงอย่างเดียวไม่พิสูจน์ผลที่คาดหวัง

Endpoint ที่คุณจะได้ใช้จริง

ผู้ติดต่อ

POST /v3/contacts สร้างผู้ติดต่อ โดยรับ email, attributes ที่ประกาศไว้, listIds และ ext_id เป็นคีย์ต้นทางที่คงที่ updateEnabled: true อัปเดตผู้ติดต่อเดิม ส่วน getId: true ขอ ID สุดท้าย Brevo ระบุฟิลด์เหล่านี้ ใช้ ext_id เดิมทุกครั้งและเก็บคู่ ID ต้นทางกับ Brevo

ก่อนเขียน กำหนดว่าระบบใดเป็นเจ้าของแต่ละแอตทริบิวต์และรายการใดรับผู้ติดต่อที่ยินยอม ระบุ listIds ให้ชัด อย่าส่ง emailBlacklisted: false ใน upsert ปกติ 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 เขียนแบบ Title-Case สำหรับ SMTP header ที่กำหนดเอง

คำขอเดียวรับผู้รับได้สูงสุด 2,000 ราย สำหรับความแตกต่างระหว่าง endpoint นี้กับการส่งแคมเปญ คู่มืออีเมลธุรกรรม ให้มุมมองเชิงกลยุทธ์การส่งข้อความไว้แล้ว

แคมเปญอีเมล

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 เมื่อการเปลี่ยนแปลงถูกนำไปใช้แล้ว

ส่วน objects 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 ดูแลไคลเอนต์ภายใต้องค์กร 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 เพียงเพื่อเรียกสอง endpoint พื้นผิว HTTP ดิบก็เล็กพอที่จะเรียกตรงได้ ซึ่งยังช่วยกันคุณจากการเปลี่ยนเวอร์ชันของ SDK ด้วย

ติดตั้งไคลเอนต์ Python ด้วย pip install brevo-python หากใช้ไม่กี่ endpoint สามารถเรียก 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 เสมอ

Webhook

Webhook คือวิธีที่คุณรู้ว่าเกิดอะไรขึ้นหลังการส่ง POST /v3/webhooks สร้างหนึ่งรายการ ด้วย url events type และตัวเลือกอย่าง channel (email หรือ sms) batched headers ที่กำหนดเอง และออบเจกต์ auth

Webhook มีสามประเภท แต่ละประเภทมีชุดอีเวนต์ของตัวเอง

• ธุรกรรม: 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 เรียกเหตุการณ์ใน payload ว่า contact_updated ยืนยันตัวตนคำขอที่รับด้วย bearer token auth หรือส่วนหัวกำหนดเองตาม คู่มือความปลอดภัย ตรวจความลับก่อนประมวลผลและอย่าบันทึกลง log

เก็บคีย์ลบซ้ำจากชนิดเหตุการณ์ ID ผู้ติดต่อ และเวลา ตลอดช่วงที่อาจส่งซ้ำ เวลาเพียงอย่างเดียวไม่เฉพาะเจาะจง เหตุการณ์อาจซ้ำหรือสลับลำดับ อ่านผู้ติดต่อปัจจุบันอีกครั้งและกระทบยอดกับแหล่งที่เชื่อถือได้ กำหนดหน้าต่างการเล่นซ้ำ ปฏิเสธเหตุการณ์เก่าหลังฟื้นระบบ และตรวจแบบเพิ่มขึ้นเป็นประจำเพื่อชดเชยเหตุการณ์ตกหล่น เว็บฮุกอย่างเดียวไม่ทำให้ซิงค์สองทาง ดู คู่มือคอนเนกเตอร์

ขีดจำกัดอัตราและการจัดการข้อผิดพลาด

ขีดจำกัดอัตรา ของ Brevo กำหนดแยกตาม endpoint และตามระดับแพ็กเกจ และช่องว่างระหว่าง endpoint นั้นกว้างมาก

Brevo ระบุ x-sib-ratelimit-limit, x-sib-ratelimit-remaining และ x-sib-ratelimit-reset สำหรับ endpoint ที่จำกัด อ่านแม้คำขอสำเร็จ หลัง 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 เมื่อเขียน ให้ตรวจว่าการเปลี่ยนแปลงเกิดขึ้นแล้วหรือไม่

การทดสอบโดยไม่ส่งอีเมลจริง

เพิ่ม header 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>" }'

ทำความเข้าใจว่าสิ่งนี้พิสูจน์อะไรและไม่พิสูจน์อะไร โหมด sandbox ตรวจสอบเฉพาะรูปแบบของคำขอ มันไม่บอกอะไรเลยเกี่ยวกับการยืนยันตัวตนผู้ส่ง การเรนเดอร์เทมเพลต หรือความสามารถในการส่งถึงกล่องขาเข้า ให้แยกบัญชี Brevo ต่างหากไว้ทดสอบการเชื่อมต่อของทุกอย่างที่แตะข้อมูลผู้ติดต่อหรือ CRM เพราะโหมด sandbox ครอบคลุมเฉพาะการส่ง ไม่ครอบคลุมส่วนที่เหลือของ API

ตรวจสอบก่อนซิงค์ผู้ติดต่อ

• เลือก ID ต้นทางที่คงที่สำหรับ ext_id และเก็บ ID Brevo
• ประกาศแอตทริบิวต์ก่อนเขียน แล้วอ่านผู้ติดต่อทดสอบกลับมา
• ใช้รายการที่ระบุชัดและหลักฐานยินยอมที่เชื่อถือได้ ข้ามผู้ถูกบล็อกหรือยกเลิกรับ
• นับรายการที่รับ นำไปใช้ ข้าม และล้มเหลวแยกกัน 202 หมายถึงรับงานเท่านั้นในขั้นแรก
• ยืนยันตัวตนและลบซ้ำเว็บฮุกการตลาด แล้วกระทบยอดสถานะ
• ดูส่วนหัวขีดจำกัดและหยุดเมื่อครบจำนวนลอง

Tajo ซิงค์ข้อมูลการค้ากับ Brevo หากพัฒนาเอง ดู คู่มือคอนเนกเตอร์