Architecture: Ad Server, SSP, and DSP

Understanding how MailAdx's three planes interact is essential for planning your integration and debugging issues at scale.

The three planes

MailAdx is organised into three functional planes that work together to deliver ads from advertiser to subscriber inbox.

Control plane (Dashboard)

The Dashboard is where humans interact with MailAdx. Publishers configure placements, floor prices, and deal terms. Advertisers create orders, upload creatives, and set budgets. Changes made in the Dashboard are staged in a configuration snapshot and published to the data plane via the Publish API.

Data plane (Ad Server)

The Ad Server is a low-latency, stateless service that processes open-time ad requests when subscribers open emails. When an email client fetches a display URL, the ad server loads the current published configuration, runs the waterfall logic, and returns the winning creative via a 302 redirect in under 5ms. The ad server is horizontally scaled to maintain latency SLAs globally.

Reporting plane

Every open-time decision, impression, click, and conversion event is written to the Reporting database asynchronously. Reports are queryable via the Dashboard UI, the Reporting API, and scheduled email exports. There is a typical 1–2 minute lag between a live event and its appearance in the reporting database.

Request flow walkthrough

  1. At send time, your ESP substitutes each subscriber's SHA-256 email hash into the ad tag embedded in your template.
  2. When the subscriber opens the email, their client fetches GET /api/v1/serving/display.
  3. The Ad Server loads the current configuration snapshot and runs the waterfall: direct-sold → PMP → OpenRTB → house ad.
  4. The winning creative is returned via a 302 redirect to the creative image URL.
  5. Clicks go through GET /api/v1/serving/click, which logs the event and redirects to the destination.
  6. The decision and delivery events are written to the Reporting database asynchronously.

Multi-tenancy model

MailAdx uses a strict multi-tenant architecture. Each account has isolated data, configurations, and reporting. Publisher accounts and advertiser accounts can be linked (for direct-sold deals) or completely separate (for programmatic). Network accounts have a parent-child hierarchy where the network operator can see aggregate data and configure shared deal terms, while publisher sub-accounts see only their own data.

API versioning

The MailAdx API uses path-based versioning (/v1/). Breaking changes are always introduced in a new version with at least 6 months of parallel support for the prior version. Non-breaking additions (new optional fields, new endpoints) are added without a version bump.