Klaviyo Integration

Embed MailAdx open-time ads in Klaviyo campaigns and flows using a profile property for the subscriber's email hash. The ad decision happens at open time — no pre-send rendering calls required.

How it works

You add an email_sha256 property to each Klaviyo profile — the SHA-256 hash of the subscriber's lowercase email address. In your email template, reference this property in the MailAdx ad block. When the subscriber opens the email, their client fetches the image URL, MailAdx runs the auction, and returns the winning creative. Impressions are only logged for emails that were actually opened.

Step 1: Add the email_sha256 profile property

Add email_sha256 to each subscriber's Klaviyo profile. You can do this via the Klaviyo Profiles API or by including the field in a list import CSV. Compute the value as:

// Node.js
import crypto from 'crypto';
const hash = crypto.createHash('sha256').update(email.toLowerCase()).digest('hex');

// Python
import hashlib
hash = hashlib.sha256(email.lower().encode()).hexdigest()

// Klaviyo Profiles API (bulk update)
POST https://a.klaviyo.com/api/profile-import/
{
  "data": [
    { "email": "user@example.com", "properties": { "email_sha256": "<hash>" } }
  ]
}

Step 2: Add the ad block to your template

In the Klaviyo template editor, add a Custom HTML block where the ad should appear. Paste the following (replace YOUR_PUB_ID and YOUR_PLACEMENT_KEY with values from Dashboard → Ad Units):

<!-- MailAdx open-time ad block — paste into Klaviyo Custom HTML block -->
<a href="https://mailadx.com/api/v1/serving/click?pub=YOUR_PUB_ID&pk=YOUR_PLACEMENT_KEY&eh={{ person.email_sha256 | default:'' }}"
   target="_blank" rel="noopener" style="display:block;text-decoration:none;">
  <img src="https://mailadx.com/api/v1/serving/display?pub=YOUR_PUB_ID&pk=YOUR_PLACEMENT_KEY&eh={{ person.email_sha256 | default:'' }}&w=728&h=90"
       width="728" height="90" border="0" alt=""
       style="display:block;max-width:100%;height:auto;"/>
</a>

Klaviyo substitutes {{ person.email_sha256 }} with the profile property value at send time. The | default:'' filter prevents merge tag literals from appearing in the email if the property is missing. The actual ad decision runs at open time.

Flow integration

The same template block works in Klaviyo flows (automations) without any changes. MailAdx handles flow-triggered sends identically to campaign sends. Because the ad decision is made at open time, even subscribers who open a flow email days after it was sent will receive a current, relevant ad — not a stale creative frozen at send time.

Testing

Send a Klaviyo test email to a profile that has the email_sha256 property set. Open the email — the MailAdx image block should display the winning creative (or a 1×1 transparent pixel if no ad fills). Click the link to verify the click redirect works. Check Dashboard → Publisher Portal to confirm the impression and click were recorded.

Troubleshooting

  • Image shows blank pixel: No ad is filling. Check that ACTIVE line items targeting this ad unit exist in the Dashboard.
  • Merge tag appears literally: The email_sha256 profile property is missing. Ensure the property is populated for all profiles before sending.
  • Image does not load: Verify publisher ID and placement key match an ACTIVE ad unit in Dashboard → Ad Units.