Test every Inbox Check endpoint in Postman in 5 minutes

Before you wire the Inbox Check API into a production pipeline, it helps to poke at every endpoint interactively. Postman is still the fastest way to do that. This guide gives you a drop-in collection — auth, create test, poll, stream, list history, verify webhook signatures, query quota — with realistic example bodies and basic response assertions.

Install Postman and import

1. Install Postman (desktop or web).
2. Download InboxCheck.postman_collection.json and InboxCheck.postman_environment.json from the docs site.
3. In Postman, click Import and drop both files in. You will see an Inbox Check collection and a matching environment in the top-right dropdown.
4. Open the environment, paste your API key into apiKey, confirm baseUrl is https://check.live-direct-marketing.online.

That is the setup. Every request in the collection inherits the key from the environment via the pre-request script, so you never hardcode credentials into a single request.

The pre-request script

The collection's pre-request script runs before every request. It checks whether you have a valid Bearer token cached; if not, it requests one using your API key and stores it with its expiry timestamp.

// Collection pre-request script
const expires = pm.environment.get('tokenExpires');
if (!expires || Date.now() > Number(expires) - 30000) {
  const res = await pm.sendRequest({
    url: pm.environment.get('baseUrl') + '/api/auth/token',
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: {
      mode: 'raw',
      raw: JSON.stringify({ apiKey: pm.environment.get('apiKey') }),
    },
  });
  const json = res.json();
  pm.environment.set('accessToken', json.accessToken);
  pm.environment.set('tokenExpires', Date.now() + json.expiresIn * 1000);
}

The 9 requests

1. Auth — exchange API key for token

Usually the pre-request script handles this silently, but the request is exposed so you can see what happens under the hood.

POST {{baseUrl}}/api/auth/token
Content-Type: application/json

{ "apiKey": "{{apiKey}}" }

2. Create a test

Kicks off a placement test. You pass a sender, subject, and either HTML content or an eml blob.

POST {{baseUrl}}/api/tests
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "sender": "hello@yourdomain.com",
  "subject": "Weekly update from YourDomain",
  "html": "<p>Welcome to YourDomain...</p>",
  "providers": ["gmail", "outlook", "yahoo", "mailru"]
}

The response returns a testId you save into an environment variable via a post-response script.

3. Get test result (poll)

GET {{baseUrl}}/api/tests/{{testId}}
Authorization: Bearer {{accessToken}}

Poll every 5–10 seconds until the top-level status is done. Most tests finish in under 2 minutes.

4. Stream via SSE

Postman supports Server-Sent Events. This request opens a connection and prints each provider verdict as it arrives — faster feedback than polling.

5. List recent tests

GET {{baseUrl}}/api/tests?limit=20
Authorization: Bearer {{accessToken}}

6. Cancel an in-flight test

DELETE {{baseUrl}}/api/tests/{{testId}}
Authorization: Bearer {{accessToken}}

7. Get quota and rate-limit status

GET {{baseUrl}}/api/me
Authorization: Bearer {{accessToken}}

8. Register a webhook

POST {{baseUrl}}/api/webhooks
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "url": "https://example.com/hooks/inbox-check",
  "events": ["test.done", "test.failed"],
  "secret": "whsec_xxx_rotate_me"
}

9. Verify a webhook payload (offline)

This is a "utility" request that does not hit the API — it uses a test script to verify the HMAC signature on a payload you paste into the body. Handy when debugging why your backend rejects a webhook.

Built-in assertions

Each request ships with basic tests so you can run the full collection via Postman's collection runner and get a red/green summary.

• Status code in the expected class (200, 201, 202).
• Response time under 5 seconds (excluding SSE).
• For POST /api/tests, the response contains a testId matching ^[a-z0-9-]+$.
• For GET /api/tests/:id, status is one of pending | running | done | failed.

Running the collection in CI

Postman collections work with Newman, Postman's CLI runner. A one-liner in GitHub Actions lets you smoke-test the API on every deploy of your integration.

# .github/workflows/smoke.yml fragment
- run: npx newman run ./postman/InboxCheck.postman_collection.json \
    -e ./postman/InboxCheck.postman_environment.json \
    --env-var apiKey=${{ secrets.INBOX_CHECK_KEY }} \
    --reporters cli,junit --reporter-junit-export ./results.xml

FAQ