Mailchimp and MailAdx: Newsletter Ad Integration Guide

Mailchimp is the most widely used email platform among newsletter publishers who are new to programmatic advertising. Connecting Mailchimp to MailAdx takes under two hours and requires no backend development — just three configuration steps in your Mailchimp account and a code snippet in your email template. This guide walks through every step from account connection to your first live impression.

How the Mailchimp–MailAdx Integration Works

The integration works through a standard HTML image element inserted into your Mailchimp email template. When a subscriber opens your newsletter, their email client requests the image URL — which points to MailAdx's ad server. The ad server receives the request, selects the best available ad for that subscriber and that moment, and responds with the ad creative. The subscriber sees the ad; you earn revenue; the impression is logged.

The key technical element is the subscriber hash. To enable frequency capping and audience targeting, the ad URL's eh parameter carries the SHA-256 hash of the subscriber's lower-cased email address, written as 64 lowercase hex characters. Mailchimp has no merge tag that computes a hash. Its merge tag cheat sheet lists no hash function of any kind. So the hash lives in an audience field that you create and fill in yourself, and the template reads it like any other merge tag. An earlier version of this guide used *|SHA256:EMAIL|*. That tag does not exist in Mailchimp and is never filled in.

This architecture means:

• No integration between Mailchimp and MailAdx is required, and MailAdx never reads your audience
• Only the hash travels in the ad URL, not the email address or any other field
• You do need to keep the hash field filled in for new subscribers (Step 3)
• Once the template is set up, no action is required on a per-campaign basis

For background on why open-time serving works this way and what it means for fill rates and CPMs, read the open-time ad serving guide first.

What You Need Before Starting

• A Mailchimp account (any paid plan, or Free plan with access to custom HTML templates)
• A newsletter with at least one existing campaign template
• A MailAdx publisher account (create one at mailadx.com/signup)
• Access to edit HTML in your Mailchimp template

The Mailchimp Free plan does allow custom HTML templates, so you do not need to be on a paid Mailchimp tier to use this integration. The custom HTML editor is available in the Mailchimp template builder under "Code your own."

Step 1: Create Your Publisher Account

Go to mailadx.com/signup and create a publisher account. During setup you'll be asked for your newsletter name, URL, and approximate subscriber count. Your account is approved and active immediately — there is no review delay.

Once inside the publisher portal, navigate to the "Placements" section. This is where you'll configure each ad slot in your newsletter.

Step 2: Create a Placement and Copy the Ad Tag

In the publisher portal under Placements, click "New Placement." You'll set:

Placement name: A descriptive internal name, e.g. "Header Banner" or "Mid-Content." This is only visible to you in reporting.

Placement key: A URL-safe identifier used in your ad tag, e.g. headeror mid_content. Keep it short and without spaces.

Ad sizes: Select the dimensions you'll use in your template. For a header placement in a 600px-wide newsletter, 600×90px and 600×100px are standard. See the ad unit best practices guidefor size recommendations by placement.

Floor CPM: The minimum CPM for paid impressions. Start with the recommended starting floor for your niche — detailed guidance in the floor CPM guide.

Then open Dashboard → Ad Tags and copy the Mailchimp version of the open-time tag. It is an HTML table with the ad image, its click link, and the label and AdChoices images. Every URL in it carries the subscriber value in eh=. The core looks like this:

<a href="https://mailadx.com/adserver/click?pub=YOUR_PUBLISHER_ID&pk=header&eh=*|EMAIL_SHA256|*&uid=*|CAMPAIGN_UID|*"
   rel="nofollow" target="_blank">
  <img src="https://mailadx.com/adserver/display?pub=YOUR_PUBLISHER_ID&pk=header&eh=*|EMAIL_SHA256|*&uid=*|CAMPAIGN_UID|*"
       style="display:flex;max-width:100%" width="auto" />
</a>

*|EMAIL_SHA256|* is the audience field you create in Step 3. *|CAMPAIGN_UID|* is Mailchimp's built-in ID for each email, which keeps the URL unique per send. Copy the tag from your dashboard rather than typing it. The dashboard fills in your publisher ID and placement key, and it switches to your own ad domain once that is active.

Step 3: Add the SHA-256 Merge Field to Mailchimp

In Mailchimp, go to Audience → Audience fields and merge tags → Create a new field. Choose a text field, name it something like “Email SHA256” and give it the merge tag EMAIL_SHA256. Use the merge tag exactly as Mailchimp shows it for the field. If Mailchimp shortens or changes it, use Mailchimp's version in the ad tag, because merge tags are case-sensitive and must match exactly.

Then fill it in, computing sha256(email.trim().toLowerCase()) as lowercase hex:

• Existing contacts: write the value with Mailchimp's API (PATCH /lists/{list_id}/members/{subscriber_hash}, setting the field in merge_fields), or import a CSV that has the hash column mapped to the field.
• New contacts: Mailchimp won't compute the value for you. Add a webhook for Subscribes that computes the hash and writes it with the same API call. Contacts whose field is empty get no ad, and Tag Health reports them as “Email hash missing”.

Fallback, if you can't maintain the field: put *|URL:EMAIL|* in eh= instead. Mailchimp's URL: function URL-encodes the contact's address. MailAdx detects an email address, lower-cases it and hashes it on receipt, and never stores the address. The trade-off is that the plaintext address is in the ad URLs of every email. Those URLs pass through mail clients and image proxies such as Gmail's, and they can appear in web access logs along the way. Prefer the hash field where you can, and cover the fallback in your privacy notice if you use it.

Step 4: Insert the Ad Tag into Your Template

Open your Mailchimp campaign template in the HTML editor. Find the location where you want the ad to appear — immediately after your newsletter header for a header placement, or after your first content section for a mid-content placement.

Paste the tag you copied in Step 2 at that position, in a Code block if you use the drag-and-drop builder. The tag is an elastic table, so in a single-column template it fills the column width. Save the template.

Step 5: Test Your Integration

Before your first live send, verify the integration by sending a test email to yourself through Mailchimp's "Send a test email" function.

Open the test email and check:

The image loads: The ad placeholder or a live ad should appear in the position where you placed the tag. If the image is broken or missing, check that the ad tag URL is correctly formed and that the publisher ID matches your MailAdx account.

The SHA-256 hash is present in the URL: the image URL's eh parameter should be 64 lowercase hex characters. If it is empty, the EMAIL_SHA256 field has no value for the test contact. If it still reads *|EMAIL_SHA256|*, the merge tag doesn't match the field. Open the image in a new tab to see the URL. Send the test to a contact whose field you have filled in.

Check the MailAdx dashboard: After opening the test email, log into the MailAdx reporting dashboard. You should see a test impression registered for your placement. This confirms end-to-end connectivity.

If the merge tag is not being processed (the URL still contains *|EMAIL_SHA256|*literally), first check that the tag matches the field's merge tag in Audience fields exactly. Then check that the HTML is in a Code block, or in a coded template, rather than a standard text block.

Troubleshooting Common Issues

Image not appearing in the email

The most common cause is a malformed ad tag URL — typically a copy-paste issue that introduced extra whitespace or removed a required parameter. Re-copy the ad tag from the MailAdx publisher portal and replace the template tag entirely. Ensure no line breaks were introduced inside the src="" attribute.

SHA-256 merge tag not being replaced

Mailchimp processes merge tags differently in its code editor vs. its drag-and-drop builder. If you're using the drag-and-drop builder, add a "Code" block and paste the raw HTML tag into that block rather than into a standard content block. Alternatively, switch to an HTML template (Mailchimp → Templates → Code your own).

Impression registered but showing house ad

If you see your configured house ad rather than a paid ad, this means no paid demand met your floor price at the time of the test impression. This is normal — particularly at the start, when the platform hasn't yet built a history of your audience's attributes. Paid demand will increase as campaign targeting data accumulates. Lower your floor temporarily to see paid ads appear during testing, then raise it to your target floor for live sends.

No impression appearing in the dashboard

Check that Apple Mail Privacy Protection isn't causing the issue. If you're testing on an Apple Mail client with MPP enabled, the prefetch from Apple's servers may be logged differently than a genuine open. Test on a Gmail or non-Apple email client to verify end-to-end connectivity without MPP interference. See the MPP guide for more detail.

Adding Multiple Placements

Once your header placement is live and verified, adding a mid-content or footer placement follows the same process: create a new placement in the publisher portal with a different placement key (e.g. mid_content), copy the new ad tag, and insert it at the appropriate position in your template.

Each placement has its own floor price, category blocklist, and demand waterfall — configure them independently. The header and mid-content placements will show separate performance data in your reporting dashboard. See the complete guide to publisher ad unit best practicesfor how to configure multiple placements optimally.

Frequently Asked Questions

Does this integration require the Mailchimp API?

Not for MailAdx. The ad tag works through HTML template editing and Mailchimp's merge tags, and MailAdx never connects to your Mailchimp account. You do need some way to fill in the EMAIL_SHA256 field: a CSV import for existing contacts, plus the Mailchimp API or a webhook for new ones. If you use the *|URL:EMAIL|* fallback instead, nothing else is needed, at the privacy cost described in Step 3.

Will this work with Mailchimp's plain-text emails?

No. Ad tags require HTML email rendering — the image tag needs to be loaded by an email client. Plain-text campaigns cannot serve ads. The integration is for HTML campaigns only.

Does the ad tag slow down email loading?

MailAdx's ad server returns a response in under 10ms for the vast majority of requests. This is imperceptible in the context of email rendering. If a subscriber's network is slow, the image may take longer to load, but this is true of any image in any email and is not specific to ad serving.

Can I use this with other ESPs besides Mailchimp?

Yes. The core integration approach — HTML image tag with SHA-256 email hash via merge tag — works with any ESP that supports custom HTML and merge variables. The syntax for the merge tag differs by platform (Klaviyo uses a different format; Beehiiv has its own variable syntax). See the ESP integration documentation for platform-specific instructions.

What happens if a subscriber has images disabled in their email client?

If images are blocked, the ad tag image doesn't load, no impression fires, and no revenue is earned for that open. This is identical to what happens with any image in any email with images disabled. The proportion of subscribers with images disabled is generally low (below 5% in most newsletter audiences) and declining as email clients default to showing images.