API reference
Open-time ad serving via display and click URLs — no JavaScript tags in the inbox.
Overview
The primary integration is an ad tag: paste HTML in your ESP template with a merge tag for each subscriber's SHA-256 email hash. When the subscriber opens the email, their client fetches /api/v1/serving/display and MailAdx runs the waterfall in real time. All trafficking, reporting, and billing is managed through the MailAdx Dashboard.
Ad tag (recommended)
Copy your ad tag from Dashboard → Ad Units. Replace {{EMAIL_SHA256}} with your ESP's merge tag syntax.
<!-- Paste in your ESP template — decision runs at open time -->
<a href="https://mailadx.com/api/v1/serving/click?pub=YOUR_PUB_ID&pk=YOUR_PLACEMENT_KEY&eh={{EMAIL_SHA256}}"
target="_blank" rel="noopener">
<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;"/>
</a>Display API
GET /api/v1/serving/display
Called by the email client when the subscriber opens the email. Runs the waterfall and 302-redirects to the winning creative image. Returns a 1×1 transparent GIF if no ad fills.
| Param | Required | Description |
|---|---|---|
| pub | yes | Publisher ID |
| pk | yes | Placement key |
| eh | no | SHA-256 hex (64 chars) of lowercase email |
| w, h | no | Creative dimensions (e.g. 728, 90) |
| nid | no | Network ID (default: net-default) |
Click API
GET /api/v1/serving/click
Wrap ad links in this URL. Logs the click event and 302-redirects to the advertiser destination. Use the same pub, pk, and eh params as the display URL.
Tracking
GET /api/v1/track/impression— 1×1 GIF pixel (used with advanced decision API responses)GET /api/v1/track/click— 302 redirect to destinationGET /api/v1/track/cv/{token}— conversion (LEADS)GET /api/v1/health— liveness + snapshot version
Advanced: Decision API
Optional for custom send pipelines that pre-render HTML per subscriber before delivery. Most publishers should use the ad tag above instead.
GET /api/v1/serving/decision
| Param | Required | Description |
|---|---|---|
| networkId | yes | Network identifier |
| publisherId | yes | Publisher ID |
| placementKey | yes | Ad unit placement key |
| emailHash | no | SHA-256 hex (64 chars) of lowercase email |
| geo | no | Country or region code |
| device | no | Desktop | Mobile | Other |
Response includes emailHtml, impressionPixelUrl, clickUrl. Empty fill → 204.
// Advanced: pre-render HTML in a custom send pipeline (optional)
const res = await fetch(
adserverUrl + '/api/v1/serving/decision' +
'?networkId=net-default' +
'&publisherId=pub_123' +
'&placementKey=newsletter/header' +
'&emailHash=' + sha256(email) +
'&geo=US&device=Other'
);
if (res.ok) {
const ad = await res.json();
template = template.replace('{{AD_SLOT}}', ad.emailHtml ?? '');
}ESP cookbook
EMAIL_SHA256 merge field and paste the ad tag. See Mailchimp guide.Need integration help?
Our team can walk through your ESP setup on a demo call.