Live Direct Marketing

Live Direct Marketing Tests API

The tests API from Live Direct Marketing — 13 operation(s) for tests.

GitHub OpenAPI

Operations 16

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /api/tests Start an inbox placement test from the web · Tests controller create #
Ask an LLM
“How do I run a free inbox placement test for my email address?”
“Can I choose which mailbox providers the web placement test checks?”
Tell an agent
Start a placement test for {email}.
Run a web inbox check for {email} against providers {providers}.
GET /api/tests/{token} Get a web placement test by token · Tests controller get #
Ask an LLM
“Where do I see the results of a placement test I started on the website?”
“Can I open a web test's report with just its token?”
Tell an agent
Show web placement test {token}.
Get the results of inbox check {token} from the website.
DELETE /api/tests/{token} Delete a web placement test · Tests controller delete test #
Ask an LLM
“Can I remove a placement test I ran on the website?”
“How do I delete a test that has no API key, only a token?”
Tell an agent destructive · confirm first
Delete web placement test {token}.
Remove inbox check {token} I started on the site.
GET /api/tests/{token}/live Stream live results of a test · Tests sse controller stream #
Ask an LLM
“Can I watch placement results arrive in real time?”
“Is there a live feed of a test's progress?”
Tell an agent
Stream live updates for test {token}.
Follow test {token} live as seeds report in.
POST /api/track/click Record a tracked click · Track controller click #
Ask an LLM
“Is there an endpoint that records link clicks for tracking?”
“Can clicks be logged without any parameters in the URL?”
Tell an agent
Record a tracked click event.
Log a click to the tracker.
POST /api/tests/{token}/finish Finish a check and get its partial report · Finish the current check and return its saved partial report #
Ask an LLM
“Can I end a placement check early and keep what's been found so far?”
“What do I get back when I finish a test before all seeds report?”
Tell an agent
Finish test {token} and return its partial report.
Stop checking {token} now and save the partial results.
POST /api/tests/{token}/warmup Move spam-placed test emails to inbox · Free warmup — move the test's spam-placed emails back to Inbox on our seed… #
Ask an LLM
“Can I move my test emails that landed in spam back to the inbox as a not-spam signal?”
“Is the free warmup safe to call twice for the same test?”
Tell an agent
Run free warmup on test {token} to move its spam-placed emails to Inbox.
Mark test {token}'s spam emails as not spam on the seed mailboxes.
POST /api/tests/{token}/repoll Re-poll a test by public token · Force IMAP re-poll of a test (within cooldown) — public by token #
Ask an LLM
“My web test email arrived late; can I make the seeds re-check without an API key?”
“How long is the cooldown between public re-polls of a test?”
Tell an agent
Re-poll seeds for web test {token} using only its token.
Force an IMAP re-check of public test {token}.
POST /api/v1/tests Create a manual deliverability test · Create a deliverability test (manual mode) #
Ask an LLM
“How do I test where my campaign email lands across all seed mailboxes?”
“Can I request screenshots of where the email landed?”
Tell an agent
Create a manual deliverability test across providers {providers}.
Give me seed addresses for a placement test with recipient {recipient}, screenshots on.
GET /api/v1/tests List my deliverability tests · List own tests (paginated by created_at cursor) #
Ask an LLM
“Which deliverability tests has my API key created?”
“Can I page back through older tests or filter them by status?”
Tell an agent
List my last {limit} deliverability tests with status {status}.
Show tests created before {cursor}.
POST /api/v1/tests/auto Create an auto-mode test for one recipient · Create a deliverability test (auto mode — per-recipient single-seed) #
Ask an LLM
“Can I test placement for one recipient by letting the provider be detected from their MX?”
“What seed is used when the recipient is on a custom domain?”
Tell an agent
Create an auto-mode deliverability test for recipient {recipient}.
Auto-test placement of mail from {sender} to {recipient}.
GET /api/v1/tests/{token} Get a test's results as JSON or PDF · Fetch test status + results (JSON or PDF) #
Ask an LLM
“Did my email land in inbox or spam, and did SPF, DKIM and DMARC pass?”
“Can I download a deliverability test result as a PDF?”
Tell an agent
Show the results of deliverability test {token}.
Download test {token} as {format}.
DELETE /api/v1/tests/{token} Delete a deliverability test · Delete a test (irreversible) #
Ask an LLM
“Can I permanently delete a test and its screenshots through the API?”
“Is deleting a v1 test reversible?”
Tell an agent destructive · confirm first
Delete deliverability test {token} and its results.
Permanently remove API test {token}.
POST /api/v1/tests/{token}/repoll Re-poll a test's seeds with an API key · Force IMAP re-poll of a test (within cooldown) #
Ask an LLM
“Delivery was delayed past the window; how do I make my API test re-check its seeds?”
“Does an API re-poll use up test quota?”
Tell an agent
Re-poll every seed of API test {token} now.
Trigger a one-shot IMAP fetch for owned test {token}.
POST /api/v1/tests/{token}/recheck Schedule a delayed placement recheck · Schedule a same-message placement recheck #
Ask an LLM
“Can I check whether the same email moved between inbox and spam a day later?”
“Does a delayed recheck send a new email or cost quota?”
Tell an agent
Schedule a placement recheck of test {token} in {hours} hours.
Recheck where test {token}'s message sits tomorrow.
GET /api/v1/tests/{token}/recheck-status Get delayed recheck snapshots · Get delayed placement snapshots and transitions #
Ask an LLM
“Did my email's placement change between the first check and the delayed recheck?”
“Where do I read the transition matrix from a scheduled recheck?”
Tell an agent
Show recheck snapshots and transitions for test {token}.
Compare the original and delayed placement of test {token}.

Documentation

📖
Documentation
https://developers.live-direct-marketing.online/
📖
APIReference
https://developers.live-direct-marketing.online/api-reference
📖
GettingStarted
https://developers.live-direct-marketing.online/quickstart
📖
Authentication
https://developers.live-direct-marketing.online/authentication
📖
Documentation
https://check.live-direct-marketing.online/docs
📖
APIReference
https://check.live-direct-marketing.online/api/docs

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/live-direct-marketing-online/refs/heads/main/openapi/live-direct-marketing-online-tests-api-openapi.yml

Other Resources

🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/live-direct-marketing-online/refs/heads/main/data-model/live-direct-marketing-online-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/live-direct-marketing-online:live-direct-marketing-online-tests-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

live-direct-marketing-online-tests-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: inbox-check Tests API
  description: Email deliverability test API for AI agents and automation. Same surface is exposed via REST (here), MCP (streamable-http at /mcp), and A2A (skill manifest at /.well-known/agent.json).
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: Tests
paths:
  /api/tests:
    post:
      operationId: TestsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestDto'
      responses:
        '201':
          description: ''
      tags:
      - Tests
      summary: Tests controller create
      x-summary-source: derived
  /api/tests/{token}:
    get:
      operationId: TestsController_get
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Tests
      summary: Tests controller get
      x-summary-source: derived
    delete:
      operationId: TestsController_deleteTest
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Tests
      summary: Tests controller delete test
      x-summary-source: derived
  /api/tests/{token}/live:
    get:
      operationId: TestsSseController_stream
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      tags:
      - Tests
      summary: Tests sse controller stream
      x-summary-source: derived
  /api/track/click:
    post:
      operationId: TrackController_click
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - Tests
      summary: Track controller click
      x-summary-source: derived
  /api/tests/{token}/finish:
    post:
      operationId: WarmupController_finish
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Finish the current check and return its saved partial report
      tags:
      - Tests
  /api/tests/{token}/warmup:
    post:
      operationId: WarmupController_warmup
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: object
      summary: Free warmup — move the test's spam-placed emails back to Inbox on our seed…
      tags:
      - Tests
  /api/tests/{token}/repoll:
    post:
      description: Same one-shot IMAP re-check as the owner-key POST /api/v1/tests/{token}/repoll, but usable by anyone who knows the test token (web/Telegram tests never have an API key to call the v1 endpoint with). 30s cooldown per token, quota NOT consumed (no email sent), refused on waiting/checking, 7-day age cap.
      operationId: WarmupController_repoll
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '201':
          description: ''
      summary: Force IMAP re-poll of a test (within cooldown) — public by token
      tags:
      - Tests
  /api/v1/tests:
    post:
      description: Returns a seed mailbox the caller must send their campaign email to (with the +token plus-addressing). Workers then poll the seed via IMAP and report placement (inbox/spam/other/not_received); polling backs off over up to a 2h window before giving up (api#27).
      operationId: V1TestsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateV1TestDto'
      responses:
        '202':
          description: ''
      security:
      - apiKey: []
      summary: Create a deliverability test (manual mode)
      tags:
      - Tests
    get:
      description: Returns tests created by this API key, newest first. Use `?cursor=` to page back.
      operationId: V1TestsController_list
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          type: string
      - name: cursor
        required: false
        in: query
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - apiKey: []
      summary: List own tests (paginated by created_at cursor)
      tags:
      - Tests
  /api/v1/tests/auto:
    post:
      description: 'For campaign-style delivery checks: pass `recipient_email` and we auto-classify the provider via MX, picking ONE matching seed (vs the manual mode which fans across all seeds). Custom-domain recipients fall back to the `ldm` spam-analyzer seed.'
      operationId: V1TestsController_createAuto
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateV1AutoTestDto'
      responses:
        '202':
          description: ''
      security:
      - apiKey: []
      summary: Create a deliverability test (auto mode — per-recipient single-seed)
      tags:
      - Tests
  /api/v1/tests/{token}:
    get:
      description: 'Returns full test snapshot: status (waiting/done/expired), per-seed results (placement, spf/dkim/dmarc, screenshot URL), aggregate summary, verdict, and recommendations. Pass `?format=pdf` or `Accept: application/pdf` to download a PDF report instead — requires `reports:pdf` scope.'
      operationId: V1TestsController_get
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      - name: format
        required: false
        in: query
        description: Response format. Default `json`. Use `pdf` for a downloadable report.
        schema:
          enum:
          - json
          - pdf
          type: string
      responses:
        '200':
          description: Owner-scoped snapshot with persisted observed-receipt evidence on each result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        received_sender_email:
                          type:
                          - string
                          - 'null'
                        received_sender_verified:
                          type:
                          - boolean
                          - 'null'
                        message_identity:
                          type:
                          - string
                          - 'null'
      security:
      - apiKey: []
      summary: Fetch test status + results (JSON or PDF)
      tags:
      - Tests
    delete:
      description: Removes the test, its results, and any associated screenshot jobs. Cannot be undone.
      operationId: V1TestsController_remove
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      security:
      - apiKey: []
      summary: Delete a test (irreversible)
      tags:
      - Tests
  /api/v1/tests/{token}/repoll:
    post:
      description: Triggers a one-shot IMAP fetch on every seed of this test. 30s cooldown per token. Quota NOT consumed (no email sent). Useful when delivery is delayed past the auto-window.
      operationId: V1TestsController_repoll
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Owner-scoped repoll snapshot with the same observed-receipt fields as GET /v1/tests/{token}.
      security:
      - apiKey: []
      summary: Force IMAP re-poll of a test (within cooldown)
      tags:
      - Tests
  /api/v1/tests/{token}/recheck:
    post:
      description: Schedules a durable re-scan of the original message after delay_hours (24 by default). Does not send a new email and does not consume test quota. Use GET /api/v1/tests/{token}/recheck-status to read both snapshots and the transition matrix.
      operationId: V1TestsController_scheduleDeferredRecheck
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleDeferredRecheckDto'
      responses:
        '202':
          description: ''
      security:
      - apiKey: []
      summary: Schedule a same-message placement recheck
      tags:
      - Tests
  /api/v1/tests/{token}/recheck-status:
    get:
      operationId: V1TestsController_deferredRecheckStatus
      parameters:
      - name: token
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
      security:
      - apiKey: []
      summary: Get delayed placement snapshots and transitions
      tags:
      - Tests
components:
  schemas:
    ScheduleDeferredRecheckDto:
      type: object
      properties:
        delay_hours:
          type: number
          description: Delay before the same-message recheck. Defaults to 24 hours.
          default: 24
          minimum: 1
          maximum: 168
    CreateV1TestDto:
      type: object
      properties:
        recipient_email:
          type: string
          format: email
        providers:
          type: array
          items:
            type: string
        meta:
          type: object
        screenshots:
          type: boolean
    CreateTestDto:
      type: object
      properties:
        emailLocale:
          type: string
          enum:
          - ru
          - en
        email:
          type: string
          maxLength: 200
          format: email
        hcaptchaToken:
          type: string
          maxLength: 4096
        providers:
          maxItems: 20
          type: array
          items:
            type: string
        presend:
          $ref: '#/components/schemas/PresendOptionsDto'
        consentVersion:
          type: string
          maxLength: 32
        consentLocale:
          type: string
          maxLength: 8
        senderLinkReports:
          type: boolean
      required:
      - email
    CreateV1AutoTestDto:
      type: object
      properties:
        recipient_email:
          type: string
          format: email
        sender_email:
          type: string
          format: email
        meta:
          type: object
      required:
      - recipient_email
    PresendOptionsDto:
      type: object
      properties:
        enableTier2:
          type: boolean
  securitySchemes:
    apiKey:
      scheme: bearer
      bearerFormat: icp_live_*
      type: http
    adminKey:
      type: apiKey
      in: header
      name: X-Admin-Key