API Documentation

Getting Started

MailCatch provides a simple REST API for creating temporary email inboxes and receiving messages. Perfect for automated testing of signup flows, OTP verification, and password resets.

Base URL

https://mcatch.dev/api

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -H "X-API-Key: mc_your_key_here" \
  https://mcatch.dev/api/inboxes

Create Inbox

POST/api/inboxes

Creates a new temporary email inbox. Returns the inbox ID and email address.

Request

curl -X POST https://mcatch.dev/api/inboxes \
  -H "X-API-Key: mc_your_key_here"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "a1b2c3d4e5f6g7h8@mcatch.dev",
  "is_active": true,
  "message_count": 0,
  "created_at": "2026-07-20T10:30:00.000Z",
  "expires_at": "2026-07-21T10:30:00.000Z"
}

Wait for Message (Long Polling)

GET/api/inboxes/{id}/wait

Waits for a new message to arrive. Returns immediately if a message is already present. Times out after 30 seconds (configurable with ?timeout=60).

Request

curl https://mcatch.dev/api/inboxes/550e8400-.../wait \
  -H "X-API-Key: mc_your_key_here"

Response

{
  "id": "msg-uuid-here",
  "from_address": "noreply@example.com",
  "subject": "Your verification code",
  "otp_code": "482913",
  "received_at": "2026-07-20T10:31:05.000Z"
}

List Messages

GET/api/inboxes/{id}/messages

Returns all messages received by the inbox.

{
  "data": [
    {
      "id": "msg-uuid",
      "from_address": "noreply@example.com",
      "subject": "Your verification code",
      "otp_code": "482913",
      "received_at": "2026-07-20T10:31:05.000Z"
    }
  ]
}

Playwright Example

import { test, expect } from '@playwright/test';

test('user signup with OTP', async ({ page, request }) => {
  // Create inbox
  const inbox = await (await request.post('https://mcatch.dev/api/inboxes', {
    headers: { 'X-API-Key': process.env.MAILCATCH_KEY! }
  })).json();

  // Fill signup form
  await page.goto('https://your-app.com/signup');
  await page.fill('#email', inbox.address);
  await page.fill('#password', 'SecurePass123!');
  await page.click('button[type="submit"]');

  // Wait for OTP email
  const message = await (await request.get(
    `https://mcatch.dev/api/inboxes/${inbox.id}/wait`
  )).json();

  // Enter OTP and verify
  await page.fill('#otp', message.otp_code);
  await page.click('#verify');
  await expect(page.locator('.welcome')).toBeVisible();
});

Cypress Example

describe('Signup', () => {
  it('verifies email with OTP', () => {
    cy.request({
      method: 'POST',
      url: 'https://mcatch.dev/api/inboxes',
      headers: { 'X-API-Key': Cypress.env('MAILCATCH_KEY') }
    }).then(({ body: inbox }) => {
      cy.visit('/signup');
      cy.get('#email').type(inbox.address);
      cy.get('#password').type('SecurePass123!');
      cy.get('form').submit();

      cy.request(`https://mcatch.dev/api/inboxes/${inbox.id}/wait`)
        .then(({ body: msg }) => {
          cy.get('#otp').type(msg.otp_code);
          cy.get('#verify').click();
          cy.contains('Welcome').should('be.visible');
        });
    });
  });
});

Rate Limits

Plan	Inboxes/month	API Keys	Retention
Free	100	1	24 hours
Pro	5,000	5	7 days
Team	50,000	Unlimited	30 days