Complete REST API documentation for Stamp0. Endpoints for managing inboxes, emails, and projects programmatically.

The Stamp0 API allows you to programmatically create inboxes, retrieve emails, and manage your testing workflows.

Full API documentation coming soon. This page will be replaced with comprehensive OpenAPI-generated documentation covering all endpoints.

Quick Start

For most use cases, we recommend using the SDK instead of calling the API directly.

import { Stamp0 } from '@stamp0/sdk';

const stamp0 = new Stamp0({
  apiKey: process.env.STAMP0_API_KEY,
});

const inbox = await stamp0.createInbox({
  projectId: 'prj_abc123',
});

Authentication

All API requests require authentication via API key:

Authorization: Bearer sk_live_your_api_key_here

See API Keys documentation for creating and managing keys.

Base URL

https://api.stamp0.com/v1

Endpoints Overview

Inboxes

Method	Endpoint	Description
`POST`	`/inboxes`	Create a new inbox
`GET`	`/inboxes/:id`	Get inbox details
`DELETE`	`/inboxes/:id`	Delete an inbox

Emails

Method	Endpoint	Description
`GET`	`/inboxes/:id/emails`	List emails in inbox
`GET`	`/inboxes/:id/emails/:emailId`	Get specific email
`DELETE`	`/inboxes/:id/emails/:emailId`	Delete an email

Projects

Method	Endpoint	Description
`GET`	`/projects`	List projects
`GET`	`/projects/:id`	Get project details

Example: Create Inbox

curl -X POST https://api.stamp0.com/v1/inboxes \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_abc123"
  }'

Response:

{
  "id": "inb_xyz789",
  "address": "abc123xyz@stamp0.com",
  "projectId": "prj_abc123",
  "createdAt": "2024-01-15T10:00:00Z"
}

Example: Get Emails

curl https://api.stamp0.com/v1/inboxes/inb_xyz789/emails \
  -H "Authorization: Bearer sk_live_your_key"

Response:

[
  {
    "id": "eml_abc123",
    "inboxId": "inb_xyz789",
    "from": "noreply@example.com",
    "subject": "Verify your email",
    "body": "Click here to verify...",
    "bodyHtml": "<html>...",
    "receivedAt": "2024-01-15T10:05:00Z",
    "read": false
  }
]

Error Handling

Errors return appropriate HTTP status codes with JSON error bodies:

{
  "error": {
    "code": "not_found",
    "message": "Inbox not found"
  }
}

Common Error Codes

Status	Code	Description
400	`bad_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key lacks permission
404	`not_found`	Resource not found
429	`rate_limit_exceeded`	Rate limit exceeded
500	`internal_error`	Server error

Rate Limiting

Default: 100 requests per 24 hours per API key
Rate limit headers included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640000000

When rate limited, you'll receive:

Status: 429 Too Many Requests
Header: Retry-After: 3600 (seconds until reset)

Next Steps

SDK Reference

Use the SDK for easier integration

API Keys

Create and manage API keys

Playwright Guide

Use the API in E2E tests

API Reference