Brevo API: πρακτικός οδηγός για προγραμματιστές

Μια εγγραφή επαφής μπορεί να επιστρέψει 201 αλλά να είναι λανθασμένη: χάθηκε το ID πηγής, επιλέχθηκε λάθος λίστα ή αγνοήθηκε προηγούμενη απεγγραφή. Πρόκειται για αποφάσεις δεδομένων, όχι απλές λεπτομέρειες HTTP.

Ο οδηγός ξεκινά με μια λειτουργική εγγραφή επαφής και συνεχίζει με ελέγχους για μικρό, επαναλήψιμο συγχρονισμό.

Τι καλύπτει το Brevo API

Τα πάντα βρίσκονται κάτω από έναν ενιαίο host και μία ενιαία διαδρομή έκδοσης. Η τεκμηρίωση για προγραμματιστές ομαδοποιεί την επιφάνεια σε τέσσερις περιοχές προϊόντος:

• Messaging: transactional email, SMS και WhatsApp, συμπεριλαμβανομένων μαζικών αποστολών, χρονοπρογραμματισμού και δραστηριότητας μηνυμάτων.
• Marketing platform: επαφές, λίστες, τμήματα και καμπάνιες email.
• eCommerce: προϊόντα, παραγγελίες και παρακολούθηση συμβάντων πελατών.
• Conversations: το widget συνομιλίας και η προγραμματιστική διαχείριση συνομιλιών.

Αυτές οι περιοχές μοιράζονται έναν λογαριασμό, μία βάση δεδομένων επαφών και ένα κλειδί API. Αυτό είναι βολικό και περιστασιακά επικίνδυνο: ένα script γραμμένο με βάση μια ιδέα δεδομένων staging μιλά στις ίδιες επαφές στις οποίες στέλνουν οι καμπάνιες σας.

Transactional έναντι marketing

Οι δύο οικογένειες συμπεριφέρονται αρκετά διαφορετικά ώστε η σύγχυσή τους να είναι το πιο συνηθισμένο σφάλμα σχεδιασμού.

Αν ακόμη αποφασίζετε αν το 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 δέχεται ξεχωριστό token και όντως χρησιμοποιεί κεφαλίδα bearer. Αυτό το token δημιουργείται στην ίδια οθόνη API keys αλλά δεν είναι εναλλάξιμο με ένα κλειδί REST.

Base URL, εκδόσεις και η πρώτη σας εγγραφή

Το base 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 μόνο του δεν αποδεικνύει το αποτέλεσμα.

Τα endpoints που θα χρησιμοποιήσετε στην πράξη

Επαφές

Το POST /v3/contacts δημιουργεί επαφή. Το σώμα δέχεται email, δηλωμένα attributes, listIds και ext_id ως σταθερό κλειδί πηγής. Το updateEnabled: true ενημερώνει υπάρχουσα επαφή και το getId: true ζητά το τελικό ID. Η Brevo τεκμηριώνει τα πεδία. Χρησιμοποιείτε το ίδιο ext_id σε κάθε εκτέλεση και διατηρείτε την αντιστοίχιση ID πηγής και Brevo.

Πριν γράψετε, ορίστε ποιο σύστημα κατέχει κάθε πεδίο και ποια λίστα δέχεται επαφές με συναίνεση. Δηλώστε ρητά το listIds. Μην στέλνετε emailBlacklisted: false σε συνηθισμένο upsert. Η Brevo προειδοποιεί ότι αλλαγή email αποκλεισμένης επαφής μπορεί να άρει τον αποκλεισμό. Χειριστείτε την αλλαγή χωριστά. Ελέγξτε αποκλεισμούς και απεγγραφές πριν προσθέσετε σε λίστα. Αν απαιτείται αυστηρή εγγύηση, επανελέγξτε πριν την αποστολή, επειδή η κατάσταση μπορεί να αλλάξει μεταξύ ανάγνωσης και εγγραφής.

Οι αναγνώσεις γίνονται μέσω 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 ώστε να μαθαίνετε το αποτέλεσμα αντί να κάνετε polling.

Transactional email

Το POST /v3/smtp/email είναι το άλογο εργασίας. Πέρα από τα sender, to, subject και htmlContent, τα πεδία που αξίζει να γνωρίζετε είναι:

• templateId με params, που αντικαθιστά το ενσωματωμένο περιεχόμενο με ένα πρότυπο Brevo και τις αντικαταστάσεις μεταβλητών του. Οι παράμετροι ανά έκδοση περιορίζονται στα 100 KB και αθροιστικά στα 1000 KB.
• messageVersions, που στέλνει εξατομικευμένες παραλλαγές σε μία κλήση, με έως 99 παραλήπτες ανά έκδοση.
• Τα tags μπορούν να βοηθήσουν στη συσχέτιση συμβάντων παράδοσης με τη ροή εφαρμογής που τα δημιούργησε.
• scheduledAt μαζί με batchId, για μελλοντικές αποστολές που ίσως θελήσετε να ακυρώσετε ως ομάδα.
• headers, σε Title-Case, για προσαρμοσμένες κεφαλίδες SMTP.

Ένα μεμονωμένο αίτημα δέχεται το πολύ 2.000 παραλήπτες. Για τη διαφορά ανάμεσα σε αυτό το endpoint και την αποστολή καμπανιών, ο οδηγός για το transactional email δίνει την οπτική της στρατηγικής μηνυμάτων.

Καμπάνιες email

Το 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 συντηρεί clients στον οργανισμό getbrevo του GitHub:

Ο client 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);

Ο client Python εγκαθίσταται με pip install brevo-python. Αν προτιμάτε να μην κουβαλάτε εξάρτηση SDK για δύο endpoints, η καθαρή επιφάνεια HTTP είναι αρκετά μικρή ώστε να την καλέσετε απευθείας, κάτι που σας προστατεύει και από τις συνεχείς αλλαγές εκδόσεων του SDK:

Εγκαταστήστε τον πελάτη Python με pip install brevo-python. Για λίγα endpoints αρκεί απευθείας 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.

Το παράδειγμα προϋποθέτει ότι ελέγξατε ήδη συναίνεση και αποκλεισμούς. Δεν άρει αποκλεισμό. Με πραγματικό κλειδί γράφει στον λογαριασμό· δοκιμάστε το πρώτα με εικονικές αποκρίσεις. Σύγκρουση αναγνωριστικών μπορεί να δώσει διάφορα 4xx. Διαβάστε την απόκριση και συμφωνήστε τα ID, χωρίς να υποθέτετε πάντα 409.

Webhooks

Τα webhooks είναι ο τρόπος με τον οποίο μαθαίνετε τι συνέβη μετά από μια αποστολή. Το POST /v3/webhooks δημιουργεί ένα, με url, events, type και προαιρετικά channel (email ή sms), batched, προσαρμοσμένες headers και ένα αντικείμενο auth.

Υπάρχουν τρεις τύποι webhook με ξεχωριστά λεξιλόγια συμβάντων:

• Transactional: sent, request, delivered, hardBounce, softBounce, blocked, spam, invalid, deferred, click, opened, uniqueOpened, unsubscribed.
• Marketing: spam, opened, click, hardBounce, softBounce, unsubscribed, listAddition, delivered, contactUpdated, contactDeleted.
• Εισερχόμενα: inboundEmailProcessed, που απαιτεί 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"
  }'

Για αλλαγές επαφών καταχωρίστε marketing webhook με contactUpdated. Η Brevo ονομάζει το συμβάν στο payload contact_updated. Πιστοποιήστε τον παραλήπτη με bearer token auth ή ειδικές κεφαλίδες σύμφωνα με τον οδηγό ασφάλειας. Ελέγξτε το μυστικό πριν την επεξεργασία και μην το καταγράφετε.

Διατηρήστε κλειδί αποδιπλοποίησης από τύπο συμβάντος, ID επαφής και χρονική σήμανση για όλο το παράθυρο επαναπαράδοσης. Μόνη η σήμανση δεν είναι μοναδική. Συμβάντα μπορεί να επαναληφθούν ή να φτάσουν εκτός σειράς. Διαβάστε ξανά την τρέχουσα επαφή, συμφωνήστε την με αξιόπιστη πηγή, ορίστε παράθυρο επανάληψης και απορρίψτε παλιά συμβάντα μετά από ανάκαμψη. Περιοδικοί αυξητικοί έλεγχοι καλύπτουν χαμένα σήματα. Το webhook μόνο του δεν υλοποιεί αμφίδρομο συγχρονισμό. Δείτε τον οδηγό συνδέσμων.

Όρια ρυθμού και χειρισμός σφαλμάτων

Τα όρια ρυθμού του Brevo ορίζονται ανά endpoint και ανά επίπεδο πακέτου, και η διαφορά μεταξύ των endpoints είναι τεράστια.

Η Brevo τεκμηριώνει τις κεφαλίδες x-sib-ratelimit-limit, x-sib-ratelimit-remaining και x-sib-ratelimit-reset σε περιορισμένα endpoints. Διαβάζετέ τις και σε επιτυχία. Μετά από 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 σε μια transactional αποστολή. Το Brevo επικυρώνει το αίτημα, επιστρέφει 201 με ένα messageId, δεν παραδίδει τίποτα και δεν γράφει καταγραφή email.

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 σημαίνει αρχικά μόνο αποδοχή.
• Πιστοποιήστε και αποδιπλοποιήστε marketing webhooks, έπειτα συμφωνήστε την κατάσταση.
• Παρακολουθείτε τα όρια και σταματήστε μετά από λίγες επαναλήψεις.

Το Tajo συγχρονίζει εμπορικά δεδομένα με τη Brevo. Δείτε τον οδηγό συνδέσμων αν φτιάχνετε μόνοι σας αυτή τη σύνδεση.