Connect Brevo: GDPR-Compliant Transactional & Marketing Email

​

Overview

​

Architecture and Dispatch Sequence

​

Step 1: Obtain Credentials from Brevo

1. Log into your account at app.brevo.com.
2. Click your profile name in the top right corner and navigate to SMTP & API.
3. Under the API Keys tab, click Generate a new API key.
4. Name your key (e.g. BrokerOS Production) and copy the generated key string. Brevo v3 API keys start with xkeysib- and are at least 40 characters long.
5. Navigate to Senders, Domains & Dedicated IPs -> Domains, add your company sending domain, and publish the recommended DKIM (k=rsa; p=...) and Brevo code TXT records to your DNS provider.

​

Step 2: Connect in the BrokerOS Web Dashboard

1. Navigate to Dashboard -> Marketing -> Email -> Settings.
2. Select the Providers & Domains tab (/dashboard/marketing/email/settings?tab=providers).
3. Click Add Provider and select Brevo from the provider catalog.
4. Fill in the modal connection fields:

5. Click Verify & Connect. BrokerOS immediately tests connectivity with GET https://api.brevo.com/v3/account. Once verified, credentials are encrypted and stored in PostgreSQL (MarketingIntegration).

​

Step 3: Configure Webhook Delivery Telemetry

1. In your Brevo portal, navigate to Transactional -> Settings -> Webhook.
2. Click Add a new webhook.
3. Enter your BrokerOS webhook endpoint URL:
   https://api.yourfirm.com/api/marketing/email/webhooks/brevo
   
4. Select checkboxes for Delivered, Opened, Clicked, Soft bounce, Hard bounce, Spam, and Unsubscribed.
5. Save the webhook. BrokerOS BrevoWebhookParser handles event ingestion automatically.

​

Webhook Event Telemetry Mapping

​

Integration Implementation Details

​

Live Account Verification

export class BrevoClient {
  private apiKey: string;

  constructor(credentials?: ProviderCredentials) {
    this.apiKey = credentials?.apiKey || process.env.BREVO_API_KEY || '';
  }

  async validate(): Promise<boolean> {
    if (!this.apiKey) return false;
    const isBrevoFormat = this.apiKey.startsWith('xkeysib-');
    if (!isBrevoFormat && this.apiKey.length < 20) return false;

    try {
      const res = await fetch('https://api.brevo.com/v3/account', {
        method: 'GET',
        headers: {
          'api-key': this.apiKey,
          Accept: 'application/json',
        },
        signal: AbortSignal.timeout(8000),
      });
      return res.status === 200 || res.status === 403;
    } catch {
      return isBrevoFormat || this.apiKey.length >= 40;
    }
  }
}

​

Outbound Transactional Dispatch

const payload: Record<string, any> = {
  sender: {
    name: options.fromName,
    email: options.fromEmail,
  },
  to: options.to.map((recipient) => ({
    email: recipient.email,
    name: recipient.name || undefined,
  })),
  subject: options.subject,
  htmlContent: options.htmlContent,
};

if (options.plainTextContent) {
  payload.textContent = options.plainTextContent;
}

if (options.replyTo) {
  payload.replyTo = { email: options.replyTo };
}

if (options.tracking?.campaignId) {
  payload.tags = [`campaign-${options.tracking.campaignId}`];
}