> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# White-label email

> Send every merchant's email in their own logo and colors from one journey and one template, with a Look up record step.

If you send email on behalf of many merchants, each one wants their customers
to see **their** brand. Instead of one template per merchant, keep each
merchant's branding as a record in your CDP and let the journey load it: a
**Look up record** step finds the right record for each run, and the email's
colors, logo and copy read from it.

A merchant with no record gets your default branding, so a new merchant never
blocks a send.

> [!TIP]
>
> Look up record loads any custom object, not just a brand. The same steps
> send an order total, a plan name or a due date the triggering event doesn't
> carry.

## 1. Store each merchant's brand

Create a custom object type for the branding, for example `merchant_brand`,
and one record per merchant. Use the merchant's ID as the record's
**external ID**, and give it the fields your email needs:

| Field | Example |
| - | - |
| `name` | `Marea` |
| `logo_url` | `https://cdn.example.com/marea/logo.png` |
| `primary_color` | `#1D5FD1` |

Records come in through the API, MCP or a sync; there's no screen for
creating them. With the API, create the type once
([`POST /api/v1/cdp/custom-objects/types`](https://docs.useboom.ai/api-reference/cdp-custom-objects/create-object-type)),
then send the records
([`POST /api/v1/cdp/custom-objects/batch`](https://docs.useboom.ai/api-reference/cdp-custom-objects/batch-upsert-objects),
up to 1,000 per call). From an AI tool connected over [MCP](https://docs.useboom.ai/use-mcp.md), you can
ask for the same thing in plain words, for example "create a merchant\_brand
type and load the brands in this CSV".

A color is a hex (`#1D5FD1`), an `rgb()` or `hsl()` with plain numbers, or a
CSS color name. Anything else is treated as empty, and the email uses its
fallback. Logos must be public `https` URLs.

### Already have brand records? Add the missing fields

If your records exist but don't have a logo or color yet, add only those
fields with `"mode": "merge"`:

```bash theme={null}
curl -X POST https://www.useboom.ai/api/v1/cdp/custom-objects/batch \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "merge",
    "createMissing": false,
    "items": [
      {
        "type": "merchant_brand",
        "externalId": "brand-marea",
        "attributes": {
          "logo_url": "https://cdn.example.com/marea/logo.png",
          "primary_color": "#1D5FD1"
        }
      }
    ]
  }'
```

> [!WARNING]
>
> Without `"mode": "merge"`, an upsert **replaces** all of a record's fields:
> every field you leave out is deleted. `"createMissing": false` makes sure
> a typo in an external ID is reported back instead of creating a new,
> empty record.

If the records come from a sync, add the two columns to the sync instead, so
the next refresh doesn't drop them.

### Check your records

Open **Objects** in your CDP and pick the type. Check that the fields your
email needs are there, with real values, for the merchants you're about to
send for.

## 2. Add a Look up record step

In the journey, add **Look up record** right before the email step, and set:

* **Record type**: `Merchant Brand`.
* **Save as**: the name later steps use, for example `brand`. It becomes
  `{{brand.logo_url}}`, `{{brand.primary_color}}` and so on.
* **How to find it**:
  * **By an ID this run carries**: insert the variable that holds the
    merchant's ID, such as `event.merchant_id` on the event that started the
    journey, a person attribute, or a field of a record an earlier step
    loaded.
  * **Linked to the person**: pick how the person is linked, up to three
    hops (person → merchant → merchant brand).
* **Fields to load**: tick every field the email uses (up to 30). Only these
  are available to later steps.
* **If several match** (linked to the person): pick the field that decides
  which record wins, and whether the highest or lowest value wins. Without
  it, several matches load nothing.

The record is read when the run reaches the step, so place it right before the
step that uses it, not before a long wait.

### By an ID, or linked to the person?

* Use **By an ID this run carries** only when the event (or the person) holds
  the brand record's **external ID** exactly. A merchant ID that isn't the
  brand record's external ID finds nothing.
* Otherwise use **Linked to the person**. The list shows every way the person
  can reach the type through your relationships, for example person →
  merchant → merchant brand, or person → buyer → merchant → merchant brand.
  If it says *no link to this type*, people aren't linked to it yet: see
  [Relationship types](https://docs.useboom.ai/relationship-types.md).
* If a person can be linked to more than one merchant (a manager of several
  stores, say), set **If several match**, or those runs load nothing and get
  your default branding.

## 3. Bind the email to the record

Open the email template in the editor:

* **Colors**: next to any color (text, heading, button, divider, background),
  choose `{ }` (*Use a variable for…*) and type `brand.primary_color`. The
  swatches you pick become the fallback, used when the value is empty or isn't
  a color.
* **Logo and images**: on an image, choose `{ }` and type `brand.logo_url`.
  The image you already had becomes the **Fallback image URL**. Always keep a
  fallback image: without one, a merchant with no logo gets an empty image.
* **Copy**: use the record anywhere you write text, for example
  `Your order with {{brand.name | default: 'us'}}` in the subject.

In the journey, the email step's preview runs the lookup on a real triggering
event, so you see the email in that merchant's brand. The editor itself shows
the fallback colors. The step's variables are split into **Content** (text)
and **Style** (colors and images).

## What happens at send time

* **The run always continues.** If no record is found, the step records **No
  record found**, the fields are empty and the email uses its fallbacks.
* **Unsafe values are removed.** Before an email goes out, Boom checks the
  values that came from your data. A value that would add a script, an event
  handler or a `javascript:` link is removed.
* **Each run shows what it found.** The run's timeline says **Record found:
  Marea**, or why nothing was found (no match, an empty ID, several matches
  and no rule).

## What publishing checks

Every `brand.<field>` the journey reads, **including inside its email
templates**, must be loaded by a Look up record step saved as `brand` that
runs before it. If the email reads `brand.primary_color` and the step doesn't
load it, publishing is refused and names the field to add.

## Test before you send

1. In the journey, open the email step. Its preview has a **Preview with**
   picker: choose a recent event for a merchant you know. The preview runs the
   lookup, so you should see that merchant's logo and colors. Try one merchant
   without a brand record too, to see the fallback.
2. Send one real run to yourself, for example by recording the triggering
   event for a test person you own.
3. Open that run's timeline. The Look up record step says **Record found:**
   and the merchant, or why nothing was found.

## Troubleshooting

| What you see | Why | What to do |
| - | - | - |
| Every email has the fallback colors and logo | The records don't have those fields, or the step doesn't load them | Check the record in **Objects**, then tick the fields under **Fields to load** |
| The timeline says **Nothing matched** | The ID isn't the brand record's external ID, or the person isn't linked to it | Switch to **Linked to the person**, or send the right ID in the event |
| The timeline says **The ID variable was empty for this run** | The event or person didn't carry the variable you picked | Check the event's properties, or pick another variable |
| The timeline says **2 records matched and no sort rule picks one** | The person is linked to more than one merchant | Set **If several match** |
| One merchant's color is ignored | The value isn't a color, for example `blue-ish` or an empty string | Store a hex such as `#1D5FD1` |
| The logo is a broken image | The URL isn't public, or the image has no fallback and the value is empty | Use a public `https` URL and keep a **Fallback image URL** |
| Publishing is refused, naming `brand.primary_color` | The email reads a field the step doesn't load | Add it to **Fields to load** |

## Other channels and uses

Saved records work in emails, WhatsApp, SMS, Instagram and Messenger messages,
HTTP requests and Dispatch event steps. Decision and Case steps can't read
`brand.*` directly; to branch on whether a record was found, use the step's
**Found** output.

## In a Transactional

A [Transactional](https://docs.useboom.ai/transactional-messages.md) has no journey to edit, so its
setup has the step instead: under **Data for the message**, click **Look up a
record**, pick **Merchant Brand** and the event field with the merchant's ID.
The fields your email uses are picked for you. A Transactional finds the record by an ID
the event carries (`event.merchant_id`), never by relationship: a customer can
be linked to several merchants, and only the event says which one this message
is for. Boom refuses to remove the lookup, or rename its **Save as**, while
the template still reads `brand.*`.

## With the API and MCP

Journeys built over the API or MCP use the same step (`LOAD_OBJECT`, with
`objectType`, `saveAs`, `lookup` and `attributes`) and the same publish checks.
A Transactional takes the same object as `lookup` on
`initiatives_transactional_configure` and `initiatives_create`.
See [Journeys](https://docs.useboom.ai/journeys.md) for the node reference and [Use Boom from
MCP](https://docs.useboom.ai/use-mcp.md) to connect an AI agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.