LDM Developers

Deliverability testing — relay reach, creative placement, marker tuning

What a placement result establishes

Tests send copies to control (seed) mailboxes. Inbox means that a tested copy was observed in that folder on a control mailbox for the sending-account × provider × content combination at the recorded time. Provider breakdown, test age and cached results matter. This is not a read of a different final recipient’s mailbox and does not guarantee their folder, reply or purchase.

Content audit, seed placement and delivery billing are separate events. The delivery billing sweep uses SENT plus at least 24 hours without a recorded bounce, not a folder observation at the final recipient. Additional preparation and approval operations can still be charged. See Billing.

Why three phases

A low inbox rate has two independent causes — the relay (sending reputation) or the creative (content). Testing them together hides which is at fault. The funnel isolates them: Phase 1 establishes the relay baseline, Phase 2 attributes a placement to the creative, Phase 3 finds the exact content marker. Each phase is an async probe — the POST returns 202 {jobId}; poll probe/:jobId for results.

Phase 1 — relay reach (qualify the channel)

Scope: deliverability:write. Send neutral, harmless baseline content from a new relay to each provider. Where it inboxes, the (relay, provider) pair is reachable; where it bounces or spams, a block-rule is written with category cannot_deliver (reason not_delivered / smtp_reject / baseline_spam). This is a per-channel reputation baseline, independent of any creative. MCP: ldm_DeliverabilityController_startRelayReach.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/relay-reach" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"relayAccountId":"<relay-account-id>","providers":["gmail.com","outlook.com"]}'

Phase 2 — creative placement (test the message)

Scope: deliverability:write. Send the creative through an already-qualified relay and see which providers inbox it and which spam it. A fresh Phase-1 baseline must exist for each (relay, provider), otherwise the call returns 400 layer1_baseline_missing — so a bad relay can never be mistaken for a bad creative. MCP: ldm_DeliverabilityController_startCreativeThroughRelay.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/creative-through-relay" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"relayAccountId":"<relay-account-id>","creativeId":"<creative-id>","providers":["outlook.com"]}'

Phase 3 — marker tuning (find the spam trigger)

Scope: deliverability:write. For a (relay, provider) where the creative spams, tuning strips one marker at a time and re-tests until placement is inbox — isolating the element that trips the filter. Tunable markers: link, image, third_party_email, spam_phrases, external_domain, utm_params, all_caps_subject, excessive_punctuation. MCP: ldm_DeliverabilityController_startCreativeTune.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/creative-tune" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<creative-id>","relayAccountId":"<relay-account-id>","provider":"outlook.com","maxAttempts":5}'

A winning variant is saved as a new clean Creative (the original is untouched) via POST /deliverability/tuned-variants/:id/promote — MCP ldm_DeliverabilityController_promoteTunedVariant. List candidates with tuned-variants.

Run the whole funnel

Scope: deliverability:write. probe/full-pipeline runs Phase 1 across every (relay × provider), auto-chains Phase 2 where the baseline inboxes, then Phase 3 on the creative culprit. Pass confirm:true when the estimated send count exceeds 50 (cost gate). MCP: ldm_DeliverabilityController_startFullPipeline.

curl -s -X POST "https://api.live-direct-marketing.online/api/deliverability/probe/full-pipeline" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"creativeId":"<creative-id>","confirm":true}'

Read results

Scope: deliverability:read. probe/:jobId returns the aggregate batch status plus the Phase-3 diagnosis (MCP getJobStatus). matrix is the dashboard — a relay × provider grid of baseline / creative / block-rule (MCP getMatrix). probes is the raw audit log; block-rules lists the marks (listBlockRules). Probe results cache for 24h — pass forceRefresh:true to a probe to bypass.

curl -s "https://api.live-direct-marketing.online/api/deliverability/matrix?creativeId=<creative-id>" \
  -H "Authorization: Bearer $LDM_KEY"

Lifting a block needs the narrower deliverability:block:delete scope (DELETE /deliverability/block-rules/:id): an agent can place blocks with deliverability:write but not silently lift them.