Skip to main content
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.
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: 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), then send the records (POST /api/v1/cdp/custom-objects/batch, up to 1,000 per call). From an AI tool connected over MCP, 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":
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.
  • 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

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 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 for the node reference and Use Boom from MCP to connect an AI agent.