Mailchimp Integration

Embed MailAdx open-time ads in your Mailchimp newsletters using a custom merge field. The ad decision happens when the subscriber opens the email — no webhooks or pre-send API calls required.

How it works

You add a custom merge field to your Mailchimp audience that stores each subscriber's SHA-256 email hash. Then paste the MailAdx ad block (two lines of HTML) into your campaign template. When the subscriber opens the email, their client fetches the image URL, MailAdx runs the auction in real time, and returns the winning creative. Impressions are only recorded for emails that were actually opened.

Step 1: Add the EMAIL_SHA256 merge field

  1. In Mailchimp, go to Audience → Manage Contacts → Settings → Audience fields and *|MERGE|* tags.
  2. Click Add A Field. Choose Text. Set the label to Email SHA256 and the merge tag to EMAIL_SHA256.
  3. Save the field.

Step 2: Populate the merge field

Before sending, import or update your subscriber list with the EMAIL_SHA256 value for each contact. Compute it 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()

You can update the field in bulk via the Mailchimp API or by importing a CSV with the EMAIL_SHA256 column.

Step 3: Add the ad block to your template

In the Mailchimp 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 Mailchimp Custom HTML block -->
<a href="https://mailadx.com/api/v1/serving/click?pub=YOUR_PUB_ID&pk=YOUR_PLACEMENT_KEY&eh=*|EMAIL_SHA256|*"
   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=*|EMAIL_SHA256|*&w=728&h=90"
       width="728" height="90" border="0" alt=""
       style="display:block;max-width:100%;height:auto;"/>
</a>

Mailchimp replaces *|EMAIL_SHA256|* with each subscriber's hash value at send time. The actual ad decision happens at open time.

Testing

Send a test campaign in Mailchimp to yourself. Open the email — the image should load and display the MailAdx ad (or a 1×1 blank pixel if no ad fills for the test hash). Verify the click link redirects correctly. Check Dashboard → Publisher Portal to confirm the impression was recorded.

Troubleshooting

  • Image shows blank pixel: No ad is filling for this slot. Check that there are ACTIVE line items targeting this ad unit in the Dashboard.
  • Merge tag appears literally in sent email: The EMAIL_SHA256 merge field was not populated for this contact. Import the field value and resend.
  • Image does not load at all: Verify the publisher ID and placement key match an ACTIVE ad unit in Dashboard → Ad Units.