Copy page

Microservices

Brevo Email Provider

Brevo Email Provider

Relevant source files

The following files were used as context for generating this wiki page:

• emailsender/src/providers/brevo.ts

The Brevo Email Provider acts as the external API adapter boundary for the EmailSender microservice. It encapsulates the complexity of the Brevo (formerly Sendinblue) REST API, providing a clean interface for sending transactional emails and mapping external delivery events to the system's internal domain statuses.

BrevoClient Implementation

The BrevoClient class is the primary integration point. It is responsible for constructing authenticated HTTP requests to the Brevo API and handling the lifecycle of an email dispatch.

API Integration Details

The client targets the Brevo SMTP API endpoint (/smtp/emails) using the standard fetch API. It handles authentication via the api-key header and manages error parsing for non-2xx responses.

Component	Description
Endpoint	Defaults to https://api.brevo.com/v1 but is configurable via the constructor emailsender/src/providers/brevo.ts:27-30.
Authentication	Uses the api-key header emailsender/src/providers/brevo.ts:39-39.
Method	HTTP POST emailsender/src/providers/brevo.ts:36-36.
Error Handling	Attempts to parse BrevoError JSON; falls back to raw status text if parsing fails emailsender/src/providers/brevo.ts:44-52.

Data Flow: Email Dispatch

The following diagram illustrates the transformation and flow of data from the internal request to the Brevo API.

Dispatch Sequence and Data Mapping

Code
sequenceDiagram
    participant S as "EmailService"
    participant B as "BrevoClient"
    participant API as "Brevo API (External)"

    S->>B: sendEmail(BrevoEmailRequest)
    Note over B: Set headers: api-key, Content-Type
    B->>API: POST /smtp/emails (JSON Body)
    alt Success (2xx)
        API-->>B: { messageId: string, messageIds?: string[] }
        B-->>S: BrevoEmailResponse
    else Error (4xx/5xx)
        API-->>B: { code: string, message: string }
        B-->>S: throw Error(`Brevo API error: ...`)
    end

Sources: emailsender/src/providers/brevo.ts:32-60

Data Structures

The provider defines specific interfaces to ensure type safety when interacting with the external API.

Request Interface (BrevoEmailRequest)

The request object supports standard SMTP fields including recipients, CC/BCC, and content types.

• Recipients: Arrays of objects containing email and optional name emailsender/src/providers/brevo.ts:2-4.
• Content: Supports both htmlContent and textContent emailsender/src/providers/brevo.ts:6-7.
• Metadata: Includes tags for tracking and categorization within the Brevo dashboard emailsender/src/providers/brevo.ts:10-10.

Response Interface (BrevoEmailResponse)

The response captures the unique identifiers generated by Brevo, which are essential for tracking delivery status via webhooks.

• messageId: The primary ID for the sent message emailsender/src/providers/brevo.ts:14-14.
• messageIds: An optional array of IDs if multiple recipients were handled individually emailsender/src/providers/brevo.ts:15-15.

Sources: emailsender/src/providers/brevo.ts:1-21

Status Mapping Logic

A critical responsibility of the BrevoClient is the mapStatus function. This method translates Brevo's specific event strings (received via webhooks) into the internal status schema used by the EmailSender microservice to maintain consistency across different providers.

Mapping Table

Brevo Status (Input)	Internal Status (Output)	Description
sent	sent	Accepted by Brevo's SMTP server.
delivered	delivered	Successfully reached the recipient's server.
opened, clicked	opened, clicked	User engagement events.
bounce, hardbounce, softbounce	bounced	Delivery failure (permanent or temporary).
spam	spam	Marked as spam by recipient.
blocked	blocked	Recipient is on a blocklist.
invalid, error	failed	Processing or formatting error.

Sources: emailsender/src/providers/brevo.ts:62-79

Integration Architecture

The BrevoClient serves as the implementation detail for the external adapter boundary. While the EmailService handles business logic (like template rendering), it relies on BrevoClient for the actual network transmission.

Provider Boundary Diagram

Code
graph TD
    subgraph "EmailSender Microservice"
        A["EmailService"] -- "calls" --> B["BrevoClient.sendEmail()"]
        C["WebhookService"] -- "calls" --> D["BrevoClient.mapStatus()"]
    end

    subgraph "External"
        B -- "HTTPS POST" --> E["Brevo API"]
        F["Brevo Webhooks"] -- "HTTPS POST" --> G["/webhook endpoint"]
        G -- "routes to" --> C
    end

    style B stroke-width:2px
    style D stroke-width:2px

Sources: emailsender/src/providers/brevo.ts:23-30, emailsender/src/providers/brevo.ts:62-62

---