API Reference

REST API

The InboxLens REST API lets you list, retrieve, and delete messages, manage API keys, and authenticate — all over HTTPS with JSON request/response bodies.

Base URL

https://testmail.neio.ai

All endpoints are prefixed with /api. Self-hosted deployments should substitute their own domain.

Authentication

Pass your API key in the Authorization header as a Bearer token, or in the X-API-Key header. Keys are prefixed with il_live_.

http

Authorization: Bearer il_live_your_api_key_here
# or
X-API-Key: il_live_your_api_key_here

Messages

GET/api/messages

List all messages received at a specific inbox address. Returns the most recent messages first, up to the specified limit.

Query Parameters

Parameter	Type	Required	Description
`to`	string	required	The inbox address to query, e.g. user@acme.testmail.neio.ai
`limit`	number	optional	Maximum number of messages to return. Defaults to 20, max 100.
`offset`	number	optional	Pagination offset. Defaults to 0.

Response

json

{
  "messages": [
    {
      "id": "msg_01hxyz...",
      "to": "user@acme.testmail.neio.ai",
      "from": "noreply@example.com",
      "subject": "Welcome to Acme!",
      "text": "Thanks for signing up...",
      "html": "<p>Thanks for signing up...</p>",
      "receivedAt": "2025-01-15T10:23:45.000Z",
      "attachments": []
    }
  ],
  "count": 1
}

GET/api/messages/latest

Long-poll for the latest unread message at an address. The request blocks until a message arrives or the timeout elapses. Ideal for CI pipelines where you trigger an action and wait for the resulting email.

Query Parameters

Parameter	Type	Required	Description
`to`	string	required	The inbox address to watch.
`timeout`	number	optional	Seconds to wait before returning 408. Defaults to 30, max 60.

Response

json

{
  "id": "msg_01hxyz...",
  "to": "user@acme.testmail.neio.ai",
  "from": "noreply@example.com",
  "subject": "Welcome to Acme!",
  "text": "Thanks for signing up...",
  "html": "<p>Thanks for signing up...</p>",
  "receivedAt": "2025-01-15T10:23:45.000Z",
  "attachments": []
}

GET/api/messages/{id}

Retrieve the full contents of a single message by its ID, including headers and attachment metadata.

Response

json

{
  "id": "msg_01hxyz...",
  "to": "user@acme.testmail.neio.ai",
  "from": "noreply@example.com",
  "subject": "Password Reset",
  "text": "Click the link to reset...",
  "html": "<p>Click the link to reset...</p>",
  "headers": {
    "Message-ID": "<abc123@example.com>",
    "X-Mailer": "SendGrid"
  },
  "receivedAt": "2025-01-15T10:23:45.000Z",
  "attachments": []
}

DELETE/api/messages/{id}

Delete a single message. Useful for cleaning up after individual test assertions.

Response

json

{ "deleted": true }

DELETE/api/messages

Delete all messages at a given inbox address. Use this in test teardown to reset state between test runs.

Query Parameters

Parameter	Type	Required	Description
`to`	string	required	The inbox address to clear.

Response

json

{ "deleted": 5 }

Authentication

POST/api/auth/signup

Create a new account and workspace. Returns a JWT token valid for 24 hours, and the workspace slug used for inbox addresses.

Request Body

Parameter	Type	Required	Description
`email`	string	required	Email address for the new account.
`password`	string	required	Password. Minimum 8 characters.
`workspaceSlug`	string	optional	Desired workspace slug (letters and hyphens only). Auto-generated from email if omitted.

Response

json

{
  "user": {
    "id": "usr_01hxyz...",
    "email": "you@example.com"
  },
  "workspace": {
    "id": "ws_01hxyz...",
    "slug": "acme"
  },
  "token": "eyJ..."
}

POST/api/auth/login

Authenticate with an existing account. Returns a short-lived JWT token. Use this token with API endpoints that require user-level auth (e.g. managing API keys).

Request Body

Parameter	Type	Required	Description
`email`	string	required	Account email address.
`password`	string	required	Account password.

Response

json

{
  "token": "eyJ...",
  "user": {
    "id": "usr_01hxyz...",
    "email": "you@example.com"
  }
}

API Keys

GET/api/keys

List all API keys for the authenticated workspace. Key values are never returned after creation — only the prefix is shown.

Response

json

{
  "keys": [
    {
      "id": "key_01hxyz...",
      "name": "ci-tests",
      "prefix": "il_live_abc1",
      "createdAt": "2025-01-10T09:00:00.000Z",
      "lastUsedAt": "2025-01-15T10:23:45.000Z"
    }
  ]
}

POST/api/keys

Create a new API key. The full key value is returned only once in this response — store it securely.

Request Body

Parameter	Type	Required	Description
`name`	string	required	Human-readable label for the key, e.g. ci-tests.

Response

json

{
  "id": "key_01hxyz...",
  "name": "ci-tests",
  "key": "il_live_abc123xyz...",
  "createdAt": "2025-01-15T10:23:45.000Z"
}

DELETE/api/keys/{id}

Permanently revoke an API key. Any requests using this key will immediately return 401.

Response

json

{ "deleted": true }

Webhooks

Coming Soon

Outbound webhooks will allow InboxLens to push new message events to your application in real time. Each delivery is HMAC-signed with your webhook secret and retried up to 3 times with exponential back-off.