SDKs

SDK Reference

Official SDKs for Node.js and Python. Both SDKs wrap the REST API with typed interfaces and convenient helpers like waitForLatest.

⬡

Node.js SDK

@inboxlens/sdk

Installation

bash
npm install @inboxlens/sdk

Initialization

Create one client instance and reuse it across your test suite. The baseUrl defaults to https://testmail.neio.ai if omitted.

typescript
const { InboxLens } = require('@inboxlens/sdk');

const inbox = new InboxLens({
  apiKey: 'il_live_your_key_here',
  baseUrl: 'https://testmail.neio.ai',
});

List messages

typescript
// List messages for an inbox
const { messages, count } = await inbox.messages.list({
  to: 'user@acme.testmail.neio.ai',
  limit: 10,
});

console.log(`Found ${count} messages`);
messages.forEach((msg) => {
  console.log(msg.subject, msg.receivedAt);
});

Wait for the latest email

The most common pattern in test suites: trigger an action in your app and block until the resulting email arrives. Returns the message object or throws if the timeout elapses.

typescript
// Long-poll — waits up to 30s for the next email
const email = await inbox.messages.waitForLatest({
  to: 'user@acme.testmail.neio.ai',
  timeout: 30,
});

console.log(email.subject);
console.log(email.html);

Get a message by ID

typescript
// Retrieve a specific message by ID
const msg = await inbox.messages.get('msg_01hxyz...');
console.log(msg.headers['Message-ID']);
console.log(msg.attachments);

Delete messages

typescript
// Delete a single message
await inbox.messages.delete(email.id);

// Clear an entire inbox
const { deleted } = await inbox.messages.clearInbox({
  to: 'user@acme.testmail.neio.ai',
});
console.log(`Deleted ${deleted} messages`);

TypeScript support

The SDK ships with full TypeScript types. No @types/ package needed.

typescript
import { InboxLens, Message } from '@inboxlens/sdk';

const inbox = new InboxLens({
  apiKey: process.env.INBOXLENS_API_KEY!,
  baseUrl: process.env.INBOXLENS_BASE_URL ?? 'https://testmail.neio.ai',
});

async function getWelcomeEmail(address: string): Promise<Message> {
  return inbox.messages.waitForLatest({ to: address, timeout: 30 });
}
🐍

Python SDK

inboxlens

Installation

bash
pip install inboxlens

Requires Python 3.9+. Works with pytest, unittest, and Robot Framework.

Initialization

python
from inboxlens import InboxLens

inbox = InboxLens(
    api_key="il_live_your_key_here",
    base_url="https://testmail.neio.ai",
)

List messages

python
# List messages
result = inbox.messages.list(to="user@acme.testmail.neio.ai", limit=10)

for msg in result["messages"]:
    print(msg["subject"], msg["receivedAt"])

Wait for the latest email

python
# Long-poll for the latest email (blocks up to 30s)
email = inbox.messages.wait_for_latest(
    to="user@acme.testmail.neio.ai",
    timeout=30,
)

print(email["subject"])
print(email["html"])

Delete messages

python
# Delete a single message
inbox.messages.delete(email["id"])

# Clear an inbox
result = inbox.messages.clear_inbox(to="user@acme.testmail.neio.ai")
print(f"Deleted {result['deleted']} messages")

pytest integration

Use a session-scoped fixture so the client is created once per test run:

python
# conftest.py
import os
import pytest
from uuid import uuid4
from inboxlens import InboxLens

@pytest.fixture(scope="session")
def inbox():
    return InboxLens(
        api_key=os.environ["INBOXLENS_API_KEY"],
        base_url="https://testmail.neio.ai",
    )

# test_signup.py
def test_welcome_email_sent(inbox, live_server):
    address = f"user+{uuid4()}@acme.testmail.neio.ai"

    # Trigger signup on your app
    requests.post(f"{live_server}/signup", json={
        "email": address,
        "password": "Password123!"
    })

    # Wait for the welcome email
    email = inbox.messages.wait_for_latest(to=address, timeout=30)

    assert email["subject"] == "Welcome to Acme!"
    assert "confirm your email" in email["html"]