Integration guide

IQMailPilot captures email sent to addresses on your server domain. Your product sends that mail over SMTP. Your tests (or any HTTP client) then read it through the REST API using an API key.

1. Create an email server in the dashboard and note its SMTP settings and domain.
2. Configure your application mailer with those SMTP settings.
3. Create an API key if your tests need to wait for or inspect messages.
4. From the test suite, authenticate with the API key and call the messages API.

Sending mail does not require an API key. An API key is required only when you call the HTTP API.

Use only the variables that match what you are integrating. Do not treat the full set as mandatory for every consumer.

Application mailer (SMTP)

Required when your application delivers mail into IQMailPilot:

The recipient is application data, not an IQMailPilot secret. You may build it at runtime (recommended for parallel tests) or store a fixed address in configuration.

Test suite or automation (API)

Required when code must list, wait for, search, or delete messages over HTTP:

*If omitted in the TypeScript SDK, the client defaults to http://localhost:3001. Production and remote environments must set the correct origin explicitly.

What each credential is for

1. Sign in and open Dashboard → Servers.
2. Select New server, enter a name, and create the server.
3. Open the server. Record:
   • Server ID — UUID used by the API (MAILPILOT_SERVER_ID).
   • Server key and domain suffix — used to form recipient addresses (local-part@<domain-suffix>).
   • Connect via SMTP — host, port, username, and a generated password.

Every address on the server domain is accepted. You do not need to register recipients before sending.

Point your existing mail transport at the SMTP values from the server page. No API key is involved in this step.

SMTP_HOST=<host from Connect via SMTP>
SMTP_PORT=<port from Connect via SMTP>
SMTP_USER=<username from Connect via SMTP>
SMTP_PASS=<password generated on the server page>

When the application sends mail, set the recipient to an address on that server's domain suffix. For automated tests, use a unique local-part per run so parallel jobs do not share the same inbox address.

<unique-local-part>@<domain-suffix-from-server-page>

After sending, confirm delivery in Dashboard → Servers by opening the server and inspecting the message list. SMTP-only integrations can stop here.

1. Open Dashboard → API keys.
2. Select New key. Provide a name that identifies the consumer (for example the CI job or service that will use it).
3. Assign permissions. For suites that only wait for and read messages, enable servers:read and messages:read. Enable write scopes only when the consumer must purge inboxes, delete messages, or manage servers.
4. Create the key and copy the secret immediately. IQMailPilot stores a hash only; the full value cannot be retrieved later.
5. Store the secret in your secret manager or CI variables. Do not commit it to source control.

Key prefixes indicate environment: mp_test_ outside production, mp_live_ in production.

Set the following for any process that calls the IQMailPilot HTTP API:

MAILPILOT_API_URL=https://api.iqmailpilot.com
MAILPILOT_API_KEY=<secret from Dashboard → API keys>
MAILPILOT_SERVER_ID=<Server ID UUID from the server page>

The test must also know the recipient address used when the application sent the message. Pass that value to wait / waitFor as sentTo.

Include the API key on every request using one of the following headers:

Authorization: Bearer <MAILPILOT_API_KEY>
X-Api-Key: <MAILPILOT_API_KEY>

• REST base path: https://api.iqmailpilot.com/api/v1
• The key is bound to a workspace. X-Workspace-Id is optional; if sent, it must match the key's workspace.
• Creating, listing, and revoking API keys requires a signed-in dashboard session. Those management routes do not accept an API key.

Prefer the long-poll wait endpoint over fixed sleeps. It returns when a matching message exists, or fails when the timeout elapses.

TypeScript SDK

pnpm add @mailpilot/sdk

import { MailpilotClient } from '@mailpilot/sdk';

const client = new MailpilotClient({
  apiKey: process.env.MAILPILOT_API_KEY!,
  baseUrl: process.env.MAILPILOT_API_URL!,
});

const serverId = process.env.MAILPILOT_SERVER_ID!;
const sentTo = process.env.MAIL_TO!; // address used when the application sent mail
const receivedAfter = new Date().toISOString();

// Trigger the email in your application, then:
const message = await client.messages.waitFor(serverId, {
  sentTo,
  receivedAfter,
  timeout: 30,
});

// Inspect message.subject, message.textBody, message.htmlBody, message.headers

Recommended matching rules

• Use a unique sentTo per test run when tests run in parallel.
• Pass receivedAfter (ISO-8601) so older messages are ignored.
• Optionally filter by subject when the application sets a stable subject line.

All paths below are relative to https://api.iqmailpilot.com/api/v1. Replace path parameters and query values with values from your environment.

Wait for a message

curl -s -G "https://api.iqmailpilot.com/api/v1/servers/$MAILPILOT_SERVER_ID/messages/wait" \
  --data-urlencode "sentTo=$MAIL_TO" \
  --data-urlencode "timeout=30" \
  -H "Authorization: Bearer $MAILPILOT_API_KEY"

List messages

curl -s "https://api.iqmailpilot.com/api/v1/servers/$MAILPILOT_SERVER_ID/messages?limit=20" \
  -H "Authorization: Bearer $MAILPILOT_API_KEY"

Get a message

curl -s "https://api.iqmailpilot.com/api/v1/servers/$MAILPILOT_SERVER_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILPILOT_API_KEY"

Search messages

curl -s -G "https://api.iqmailpilot.com/api/v1/search/messages" \
  --data-urlencode "q=$QUERY" \
  -H "Authorization: Bearer $MAILPILOT_API_KEY"

Purge a server inbox

curl -s -X POST "https://api.iqmailpilot.com/api/v1/servers/$MAILPILOT_SERVER_ID/purge" \
  -H "Authorization: Bearer $MAILPILOT_API_KEY"

Endpoints

Interactive OpenAPI documentation: https://api.iqmailpilot.com/docs

Scopes apply to API-key authentication only. Dashboard sessions use workspace roles instead.

Minimum for typical CI assertions: servers:read and messages:read. Add messages:write only if the job purges or deletes messages.

• Store API keys and SMTP passwords outside the repository.
• Issue a separate API key per environment or pipeline so revocation is scoped.
• Grant the minimum scopes required for each key.
• Revoke a compromised key from Dashboard → API keys.
• SMTP credentials and API keys are independent. Rotating one does not rotate the other.