Connect your email platform

Point OmniLab at the email service that actually delivers your messages, so triggered sends go out from your own sending domain.

5 min read

Do this once for your account: the key lives in the Global organisation and serves every organisation. Triggered messages then arrive from your sending domain and show up in your existing reporting.

Before you begin

  • You need Admin access to reach the settings where this is done.
  • Choose the platform that sends: Brevo, Mailchimp, Salesforce Marketing Cloud, or another service with an API.
  • Have someone technical available: the connection is a Function, which is code.
  • In your email platform, create an API key that can only send transactional messages. A narrow key limits what a leak could do.

Create a secret bundle

In the organisation switcher, choose Global, and select General Settings:

  1. Select the Functions tab.

    Enterprise Settings with the Functions tab highlighted

  2. Select New secret.

    Functions tab with the New secret button highlighted

  3. Enter a Key, here brevo. You can't change it later.

    New secret bundle window with the Key brevo, highlighted

    It must start with a letter, followed by lowercase letters, digits or underscores.

  4. Enter a Display name, here Brevo Production.

    New secret bundle window with the Display name Brevo Production, highlighted

  5. Select Create bundle.

    New secret bundle window with the Create bundle button highlighted

Add the key to the bundle

The bundle opens once it's created.

  1. Select Add secret.

    Secret bundle window with the Add secret button highlighted

  2. Enter API_KEY as the key.

    Secret bundle window with API_KEY in the new row, highlighted

  3. Enter your platform's API key as the value.

  4. Select Save secrets.

    Secret bundle window with the Save secrets button highlighted

Values are hidden once saved: a Function can use them, but nobody can read them back.

Hand over to your developer

Your developer binds the bundle to a Function, on the Function's Settings tab, and writes the code that calls your platform's send API: see Configure runtime and secrets. What runs the Function depends on the email: an event such as a won reward for transactional emails, the contact.verify hook for double opt-in, or Notification sent for campaign notifications.

Send campaign notifications through your platform

The Custom Email Provider add-on sends a campaign's notifications through your own platform, instead of Cheetah or Salesforce Marketing Cloud. You still write them in Build > Notifications. OmniLab builds each email with the organisation's sender, header and footer, then hands it to your Function, which sends it.

Turn on the add-on

In the campaign, open Build > Settings. Then:

  1. On Advanced Settings, select the edit button.

    Advanced Settings card with its edit button highlighted

  2. Select the Addons tab.

    Advanced Settings with the Addons tab highlighted

  3. Select Add Item.

    Addons tab with the Add Item button highlighted

  4. Under Select Addon, choose Custom Email Provider.

    New add-on with Custom Email Provider in Select Addon, highlighted

  5. Turn on Is Addon Active.

    Custom Email Provider add-on with Is Addon Active turned on, highlighted

  6. Select Save.

    Advanced Settings footer with the Save button highlighted

Then publish the campaign again. Only one email platform can be on: turn off Is Addon Active on any Cheetah or Salesforce Marketing Cloud add-on, or publishing is blocked. As with Cheetah, booking reminders aren't sent.

What the Function receives

Your developer subscribes a platform event Function to Notification sent, in the Other group: see Platform event functions. Each event carries the finished email, in the campaign's default language:

  • rendered: the subject, preheader and html. The HTML already holds the header, the footer and every button, such as a voucher download or a waitlist invitation's Confirm Booking and Refuse Booking.
  • sender: from_email, from_name, reply_to_email and reply_to_name, from the organisation's Notifications settings.

Notifications sent through Cheetah or Salesforce Marketing Cloud trigger the same event without these fields, so the Function skips them. The email goes to the event's contact: read their address with OmniLab.Contact.get.

user.ts — send campaign notifications with Brevo
import { OmniLab } from "./omnilab";
import type { PlatformEventHandler } from "./omnilab";

type NotificationSent = {
  contact?: { contact_id?: string };
  provider?: string;
  rendered?: { subject: string; preheader?: string; html: string };
  sender?: {
    from_email: string;
    from_name?: string;
    reply_to_email?: string;
    reply_to_name?: string;
  };
};

export const onPlatformEvent: PlatformEventHandler = async (event) => {
  const data = event.data as NotificationSent;
  const { rendered, sender } = data;
  const contactId = data.contact?.contact_id;

  // Notifications sent by Cheetah or Salesforce Marketing Cloud arrive here too.
  if (data.provider !== "CUSTOM_EMAIL_PROVIDER" || !rendered || !sender || !contactId) {
    return;
  }

  const contact = await OmniLab.Contact.get(contactId);

  const response = await OmniLab.Http.post("https://api.brevo.com/v3/smtp/email", {
    headers: {
      "content-type": "application/json",
      "api-key": OmniLab.Config.getSecret("brevo.API_KEY"),
    },
    body: JSON.stringify({
      sender: { email: sender.from_email, name: sender.from_name || undefined },
      replyTo: sender.reply_to_email
        ? { email: sender.reply_to_email, name: sender.reply_to_name || undefined }
        : undefined,
      to: [{ email: contact.email }],
      subject: rendered.subject,
      htmlContent: rendered.html,
    }),
  });

  if (!response.ok) {
    throw new Error("Brevo refused the send: HTTP " + response.status);
  }
};

This needs api.brevo.com in the Function's allowed hosts, and the brevo bundle bound to it. The same event can reach the Function twice: pass event.id as your platform's idempotency key if it accepts one. See How platform events are delivered.

Update your Salesforce Marketing Cloud templates

Cheetah and Custom Email Provider add the email's buttons themselves. With Salesforce Marketing Cloud, OmniLab sends each email's details to your Marketing Cloud journey, and your own templates build the email. Before a campaign uses one of these emails, ask your Marketing Cloud team to update the journey and its templates:

EmailWhat the template must add
Winner, when the prize is a link, such as a PDF voucher, and Show Winner Ticket is onA button that opens the link, with the label OmniLab sends: Download unless the campaign's wording changes it
Waitlist JoinedA new email telling the visitor they're on the waitlist for a slot
Waitlist InvitationA new email with two buttons, one to confirm the place and one to refuse it. Use the two links OmniLab sends exactly as they arrive.

Until the invitation template has its buttons, invited people can confirm only from the event page. A visitor who gets a place from the waitlist receives the usual Booking Confirmation email.

You can paste the add-on's options, such as eventDefinitionKey or sfmcMid, straight from Marketing Cloud: spaces around a value are ignored. An option that is blank, or holds only spaces, counts as missing.

Send yourself a test

  1. Trigger the action in a test campaign.
  2. Check the message arrives from the right sender, with the right template.
  3. Check it appears in your platform's own sending log.
  4. Check your spam folder. A new integration's first sends are often filtered.

If something's blocked

  • The Function runs but nothing arrives: a successful run means your platform accepted the request, not that it delivered the message. Check your platform's delivery log next.
  • Messages arrive from the wrong sender: for triggered sends, the sender is set in your platform or in the Function's payload, not in Studio. With Custom Email Provider, it's the organisation's Sender From Email, unless your Function replaces it.
  • It works in staging but not in production: each environment has its own bundles. Check the bundle exists in production, with the same key.
  • A notification shows as sent but never arrived: with Custom Email Provider, an email counts as sent once it's handed to your Function. Check the Function's Executions tab, then your platform's delivery log.
  • The Function never runs for a notification: check the notification is switched on in Build > Notifications. Then check the organisation has a Sender From Email in Organization Settings > Notifications: without a sender address, no email is built.

Next steps

On this page