Klaviyo email heroes

Stage 1: Add your brand on Brandiseer

1. Go to brandiseer.com. In the homepage input, enter your company website URL and click Try My Brand.
2. Wait about one minute while Brandiseer analyses the site and picks a logo and visuals.
3. Review those visuals carefully. They teach Brandiseer your look. Every later Klaviyo still is influenced by what you leave here.
4. Remove anything off-brand (partner logos, stock, irrelevant screenshots). Add campaign creatives or product photography that match the look you want.
5. Click Add Brand, sign up if prompted, then wait about 30 seconds for the brand profile to finish.

Agencies repeat this once per client. Do not point two Klaviyo accounts at one Brand ID.

Stage 2: API key and Brand ID

1. Open brandiseer.com/developers or Settings → API.
2. Create an API key (bds_...). Put it in the agent host's secret store. Do not paste it into a Klaviyo template, a campaign, Slack, or a git repo.
3. Copy the Brand ID (bds_c_...).
4. Confirm the key with GET https://brandiseer.com/api/v1/credits and GET https://brandiseer.com/api/v1/brands, header X-API-Key. The credits JSON includes credits. The brands list includes each brand id.
5. Optional reachability check, no key required: GET https://brandiseer.com/api/v1/health returns { "status": "ok" }.

Read guide/docs and guide/image once while you write the standing instructions. Those pages are the live contract if a field name ever moves.

Stage 3: Connect Brandiseer to the agent host

Use Cursor or Cowork. One host is enough.

A. MCP

1. Add the Brandiseer MCP server at https://brandiseer.com/api/mcp.
2. Authenticate with Authorization: Bearer and the API key, in the secret field your host provides.
3. Confirm the tool list shows brandiseer_list_brands, brandiseer_check_credits, and brandiseer_generate_image. If a fourth Brandiseer tool appears, ignore it until guide/docs documents it.

B. REST

1. On Developers, open View Docs and use Copy for LLM if you want the reference inside the session.
2. Tell the agent to prefer POST https://brandiseer.com/api/v2/generate or POST https://brandiseer.com/api/v2/generate/async with X-API-Key.
3. If Design mode times out, switch that call to async and poll GET https://brandiseer.com/api/v2/jobs/:jobId every 3 to 5 seconds.

Stage 4: Save the standing instructions

1. Paste the System prompt from this guide into the Cursor rule or Cowork instructions that will run email stills.
2. Fill the defaults the prompt asks for: Brand ID, default crops per slot, resolution, mode, and whether useLogo is on when the brief is silent.
3. Ask the agent to call brandiseer_list_brands (or GET /api/v1/brands) and confirm the Brand ID exists before the first paid still.

Stage 5: Smoke test a hero in an image block

1. Ask for one email hero with a layout-only brief (the Spring hero in Example flows).
2. Confirm the agent checked the brand, avoided colour and mood words, and returned imageUrl plus crop, mode, and a placement note.
3. In Klaviyo, open a draft campaign or an unsent template. Drag an image block to the top of the canvas. Add the still by Import Image (paste imageUrl), by uploading the downloaded file, or by choosing it from the Image Library after you have uploaded it under Content > Images & brand > Images.
4. Set alt text, a link address if the hero should be clickable, alignment, and width. Klaviyo recommends a 600px content width, full-width images about 600 to 1000px wide and under 2000px tall, and files around 1MB or smaller. The editor accepts up to 10MB. A large Brandiseer still can be inserted and then resized in the block. Klaviyo's own tip for crispness is to use a larger source and display it smaller.
5. Use Preview & test. For a campaign or a list, segment, price-drop, or date-triggered flow, search a profile. For a metric-triggered flow, preview by the triggering event. Leave the campaign unsent. Do not change a flow's status.
6. Send a second brief that only says "make the hero premium and moody". The agent should ask what is physically in the frame instead of generating.

If the hero must sit behind a Klaviyo text block and button, use a section background instead of baking the headline into the image. That path is in the next stage. Prefer the image block when inbox support matters: Klaviyo documents that Outlook for Windows does not support background images, and that Yahoo Mail and AOL have partial support.

Stage 6: Optional image library import (Images API)

Skip this stage if people will import or upload by hand. Use it only when a private key already exists and the still must appear in the library before someone opens the template.

1. Create the key with the images:write scope. Authentication is documented on Upload Image From URL and the API overview: header Authorization: Klaviyo-API-Key <private-key>, header revision (use the default printed on the endpoint page; this guide saw 2026-07-15), and accept plus content-type of application/vnd.api+json. This is not the Brandiseer key.
2. Generate the still in Brandiseer first. Klaviyo has to be able to fetch import_from_url. The same page limits that import to jpeg, png, and gif, and to 5MB. If imageUrl is not public, the file is larger than 5MB, or Klaviyo rejects the format, stop the API call. Download the file and upload it in the template editor instead (10MB there; JPEG, PNG, GIF, and WebP that Klaviyo converts to PNG, except animated WebP).
3. Import with the documented call: POST https://a.klaviyo.com/api/images. Rate limits on that page: burst 3/s, steady 100/m, daily 100/d. Body:

{
  "data": {
    "type": "image",
    "attributes": {
      "import_from_url": "https://...",
      "name": "spring-email-hero",
      "hidden": false
    }
  }
}

import_from_url is required. name defaults to the filename if you omit it. If the name already exists, Klaviyo adds a suffix. Keep hidden false so the file shows in the asset library. A data URI is also accepted on that page. Prefer the public imageUrl when it meets the 5MB and format rules.

4. A 201 body includes data.id and data.attributes (name, image_url, format, size, hidden, updated_at). The links.self value looks like https://a.klaviyo.com/api/images/{id}/. Confirm with GET https://a.klaviyo.com/api/images (the overview's list example) using the same key and revision header. The Klaviyo-hosted image_url is what you then pick in the template. It is not yet inside an image block.
5. If you already have the file on disk and the URL import failed, the file upload is POST https://a.klaviyo.com/api/image-upload with content-type: multipart/form-data, form fields file (required), optional name, and optional hidden. The overview's example uses the same Authorization and revision headers. Same 5MB jpeg, png, or gif limit. A person still places the file.
6. Open the draft template, drag an image block, and choose the image from the Image Library. Do not send the campaign in the smoke test.

The editor's automatic compression review (compare original and compressed, or an upload setting of Compare, Use originals, or Use compressed) applies when a person uploads in the product. It is not part of the API body above. GIFs are not compressed by that tool.

Stage 7: Section background, when text must sit on the image

Skip this unless the brief needs Klaviyo text or buttons on top of the still. Klaviyo recommends this over a single image full of text, because recipients who block images, and people using screen readers, still get the text. Background images fail in some inboxes (see Limits & FAQ), so also set a section colour close to the image.

1. Download the still. The background article does not describe an Import URL field. It says: open the section Styles tab, find Background, click +, then Browse Image Library and upload.
2. Add a text block and, if you need one, a button, in that section. Leave those words out of the Brandiseer prompt. Tell the agent "empty region" instead.
3. In Format, pick Original size, Fit, Fill, or Tile. Display on is Content or Section, which chooses whether the image stays in the content width or spans the section.
4. Turn Section color on and pick a fallback colour. For a whole-template background, use the template Styles tab, click +, and choose a library image or upload. Set a template background colour as well. Full steps: background images.
5. Preview. Do not send.