# Inboxical — Email Testing API for Developers

> Create isolated test inboxes, send emails from your test suite, and verify delivery via REST API. No SMTP config needed.

## What is Inboxical?

Inboxical is a cloud-hosted email testing API built for developers who need reliable email verification in automated test suites and CI/CD pipelines. Instead of using shared inboxes, fake SMTP servers, or mocking email delivery, Inboxical provides real, isolated test inboxes via a simple REST API.

## The Problem Inboxical Solves

Testing email delivery in automated tests is hard:

1. **Shared inboxes cause conflicts** — When multiple tests or team members share the same inbox, tests become flaky because they pick up each other's messages.
2. **SMTP configuration is complex** — Setting up and maintaining SMTP servers for testing adds unnecessary infrastructure burden.
3. **Polling loops are fragile** — Most solutions require polling for new messages, leading to race conditions, timeouts, and slow tests.
4. **Mocking hides real bugs** — Mocking email delivery skips the actual sending path, so bugs in templates, encoding, attachments, and delivery logic go undetected until production.

## How Inboxical Works

### Step 1: Create an isolated inbox
```bash
curl -X POST https://api.inboxical.com/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY"
```
Response:
```json
{
  "id": "ix_3f9a",
  "address": "ix_3f9a@in.inboxical.com",
  "createdAt": "2026-03-26T10:00:00Z"
}
```

### Step 2: Trigger your app to send email
Point your application at the test inbox address. Works from CI, local dev, or staging.

### Step 3: Wait for the message
```bash
curl https://api.inboxical.com/inboxes/ix_3f9a/messages/latest?waitFor=30000 \
  -H "Authorization: Bearer YOUR_API_KEY"
```
The `waitFor` parameter uses long-polling — the request blocks until a message arrives or the timeout expires. No polling loops needed.

### Step 4: Assert
Check subject, body, attachments, headers — whatever your test needs.

## Key Features

### Long-Polling Wait Endpoint
Unlike other email testing tools that require polling loops, Inboxical's `/messages/latest?waitFor=30000` endpoint blocks until an email arrives. This eliminates race conditions and makes tests faster and more reliable.

### OTP/Verification Code Extraction
Automatically extract one-time passwords and verification codes from email bodies. No regex needed in your test code.

### Webhooks
Configure webhook URLs per inbox. Inboxical POSTs to your endpoint the moment a message arrives — ideal for event-driven test architectures.

### Official SDKs

#### Node.js SDK (@inboxical/sdk)
```javascript
import { Inboxical } from '@inboxical/sdk'

const client = new Inboxical({ apiKey: process.env.INBOXICAL_API_KEY })
const inbox = await client.createInbox()
// trigger your app to send email to inbox.address
const message = await client.waitForMessage(inbox.id, { timeout: 30000 })
expect(message.subject).toBe('Welcome!')
```

#### Playwright Plugin (@inboxical/playwright)
```typescript
import { test, expect } from '@playwright/test'
import { inboxicalFixture } from '@inboxical/playwright'

const testWithInbox = test.extend(inboxicalFixture())

testWithInbox('user receives welcome email', async ({ page, inbox }) => {
  await page.goto('/signup')
  await page.fill('[name=email]', inbox.address)
  await page.click('button[type=submit]')
  const message = await inbox.waitForMessage({ timeout: 30000 })
  expect(message.subject).toContain('Welcome')
})
```

#### Cypress Plugin (@inboxical/cypress)
```javascript
describe('Email verification', () => {
  it('sends OTP email', () => {
    cy.createInbox().then((inbox) => {
      cy.visit('/login')
      cy.get('[name=email]').type(inbox.address)
      cy.get('button[type=submit]').click()
      cy.waitForMessage(inbox.id, { timeout: 30000 }).then((msg) => {
        expect(msg.subject).to.include('Verification')
      })
    })
  })
})
```

## API Reference

### Inboxes
- `POST /inboxes` — Create a new isolated inbox
- `GET /inboxes` — List all inboxes
- `GET /inboxes/:id` — Get inbox details
- `DELETE /inboxes/:id` — Delete an inbox and its messages

### Messages
- `GET /inboxes/:id/messages` — List all messages in an inbox
- `GET /inboxes/:id/messages/latest` — Get the latest message
- `GET /inboxes/:id/messages/latest?waitFor=30000` — Long-poll for the next message (blocks until arrival or timeout)
- `DELETE /inboxes/:id/messages/:messageId` — Delete a specific message

### Webhooks
- `POST /webhooks` — Create a webhook
- `GET /webhooks` — List webhooks
- `PUT /webhooks/:id` — Update a webhook
- `DELETE /webhooks/:id` — Delete a webhook
- `POST /webhooks/:id/test` — Send a test webhook payload

### API Keys
- `POST /api-keys` — Create an API key
- `GET /api-keys` — List API keys
- `DELETE /api-keys/:id` — Revoke an API key

### Teams
- `POST /teams` — Create a team
- `GET /teams` — List teams
- `POST /teams/:id/invite` — Invite a member
- `DELETE /teams/:id/members/:userId` — Remove a member

## Pricing

| Plan | Price | Inboxes/month | Messages/month | Retention | Webhooks |
|------|-------|---------------|----------------|-----------|----------|
| Free | $0 | 100 | 500 | 3 days | No |
| Starter | $9/mo | 1,000 | 5,000 | 30 days | Yes |
| Pro | $29/mo | 10,000 | 50,000 | 90 days | Yes |
| Business | $79/mo | 100,000 | 500,000 | 1 year | Yes |

## Comparisons with Alternatives

### Inboxical vs Mailtrap
Mailtrap is an email testing tool focused on a web UI for inspecting emails. Inboxical is API-first, designed for automated tests. Key differences: Inboxical has a long-polling wait endpoint (Mailtrap doesn't), Inboxical offers Playwright and Cypress SDKs (Mailtrap doesn't), and Inboxical's free tier includes 100 inboxes/month (Mailtrap limits to 50/month).

### Inboxical vs Mailosaur
Mailosaur is a full-featured email and SMS testing platform starting at $9/month with no free tier. Inboxical offers a generous free tier, has a simpler API, and includes a unique long-polling wait endpoint. Both offer Playwright and Cypress integrations.

### Inboxical vs Ethereal Email
Ethereal is a free fake SMTP service by Nodemailer. It's great for manual inspection but has no API for automated testing, no message retention guarantees, and no SDKs. Inboxical provides a proper REST API designed for CI/CD automation.

### Inboxical vs MailHog
MailHog is a self-hosted open-source SMTP testing tool. It requires infrastructure management, has no long-polling, and stores messages only in memory (lost on restart). Inboxical is cloud-hosted with persistent storage and requires zero infrastructure.

### Inboxical vs Mailpit
Mailpit is a modern MailHog alternative (also self-hosted). While it has a better UI and API than MailHog, it still requires self-hosting and has a 500-message limit. Inboxical is a managed service with higher limits and framework SDKs.

## CI/CD Integration

### GitHub Actions
```yaml
- name: Run email tests
  env:
    INBOXICAL_API_KEY: ${{ secrets.INBOXICAL_API_KEY }}
  run: npx playwright test
```

### GitLab CI
```yaml
test:
  variables:
    INBOXICAL_API_KEY: $INBOXICAL_API_KEY
  script:
    - npx playwright test
```

## Links

- Website: https://inboxical.com
- Documentation: https://docs.inboxical.com
- API Reference: https://docs.inboxical.com/api/inboxes
- Node.js SDK: https://www.npmjs.com/package/@inboxical/sdk
- Playwright Plugin: https://www.npmjs.com/package/@inboxical/playwright
- Cypress Plugin: https://www.npmjs.com/package/@inboxical/cypress
- GitHub: https://github.com/inboxical/inboxical