Stamp0 JavaScript/TypeScript SDK for programmatic email inbox management. Create inboxes, wait for emails, and integrate with your tests.

The Stamp0 SDK provides a simple interface for creating inboxes and managing emails programmatically. Use it in your tests, CI pipelines, or any Node.js application.

Installation

npm install @stamp0/sdk

Quick Start

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

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

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

console.log(inbox.address); // abc123xyz@stamp0.com

// Wait for an email
const email = await stamp0.waitForEmail({
  inboxId: inbox.id,
  timeout: 30000,
});

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

Configuration

Initialization Options

const stamp0 = new Stamp0({
  // Required: Your API key
  apiKey: 'sk_live_...',

  // Optional: Custom API base URL (for self-hosted)
  baseUrl: 'https://api.stamp0.com',

  // Optional: Request timeout in milliseconds
  timeout: 30000,
});

Environment Variables

The SDK can read configuration from environment variables:

STAMP0_API_KEY=sk_live_your_api_key_here

// Will use STAMP0_API_KEY from environment
const stamp0 = new Stamp0();

API Reference

createInbox

Create a new email inbox.

const inbox = await stamp0.createInbox({
  // Required: Project to create inbox in
  projectId: 'prj_abc123',
});

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

getInbox

Get details about an existing inbox.

const inbox = await stamp0.getInbox({
  inboxId: 'inb_xyz789',
});

deleteInbox

Delete an inbox and all its emails.

await stamp0.deleteInbox({
  inboxId: 'inb_xyz789',
});

Deleting an inbox is permanent and cannot be undone.

getEmails

Get all emails in an inbox.

const emails = await stamp0.getEmails({
  inboxId: 'inb_xyz789',
});

// Returns array of emails:
// [
//   {
//     id: 'eml_abc123',
//     from: 'sender@example.com',
//     subject: 'Welcome!',
//     body: 'Hello...',
//     bodyHtml: '<html>...',
//     receivedAt: '2024-01-15T10:05:00Z',
//     read: false
//   }
// ]

waitForEmail

Wait for an email to arrive in an inbox. Polls until an email is received or timeout is reached.

const email = await stamp0.waitForEmail({
  // Required: Inbox to wait for email in
  inboxId: 'inb_xyz789',

  // Optional: Timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Polling interval in milliseconds (default: 1000)
  interval: 1000,
});

getEmail

Get a specific email by ID.

const email = await stamp0.getEmail({
  inboxId: 'inb_xyz789',
  emailId: 'eml_abc123',
});

deleteEmail

Delete a specific email.

await stamp0.deleteEmail({
  inboxId: 'inb_xyz789',
  emailId: 'eml_abc123',
});

markAsRead

Mark an email as read.

await stamp0.markAsRead({
  inboxId: 'inb_xyz789',
  emailId: 'eml_abc123',
});

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Stamp0, Inbox, Email } from '@stamp0/sdk';

const stamp0 = new Stamp0({ apiKey: '...' });

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

const email: Email = await stamp0.waitForEmail({
  inboxId: inbox.id,
});

Type Definitions

interface Inbox {
  id: string;
  address: string;
  projectId: string;
  createdAt: string;
}

interface Email {
  id: string;
  inboxId: string;
  from: string;
  subject: string;
  body: string;
  bodyHtml: string;
  receivedAt: string;
  read: boolean;
}

Error Handling

The SDK throws typed errors for different failure scenarios:

import { Stamp0, Stamp0Error, RateLimitError, NotFoundError } from '@stamp0/sdk';

try {
  const inbox = await stamp0.createInbox({ projectId: 'prj_abc123' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof NotFoundError) {
    console.log('Project not found');
  } else if (error instanceof Stamp0Error) {
    console.log('API error:', error.message);
  }
}

Error Types

Error	Description
`Stamp0Error`	Base error class for all SDK errors
`AuthenticationError`	Invalid or missing API key
`NotFoundError`	Resource not found
`RateLimitError`	Rate limit exceeded
`ValidationError`	Invalid request parameters
`TimeoutError`	Request or wait timed out

Examples

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

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

async function testSignupFlow() {
  // Create inbox
  const inbox = await stamp0.createInbox({
    projectId: process.env.STAMP0_PROJECT_ID!,
  });

  // Use inbox.address in your signup form
  // ... your test code here ...

  // Wait for verification email
  const email = await stamp0.waitForEmail({
    inboxId: inbox.id,
    timeout: 30000,
  });

  // Extract verification link
  const verifyLink = email.body.match(/https?:\/\/[^\s]+verify[^\s]*/)?.[0];

  // Continue with verification
  // ... your test code here ...
}

Multiple Emails

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

  // Trigger action that sends multiple emails
  // ...

  // Wait a bit for all emails to arrive
  await new Promise(resolve => setTimeout(resolve, 5000));

  // Get all emails
  const emails = await stamp0.getEmails({ inboxId: inbox.id });

  // Find specific email
  const welcomeEmail = emails.find(e =>
    e.subject.toLowerCase().includes('welcome')
  );

  const verificationEmail = emails.find(e =>
    e.subject.toLowerCase().includes('verify')
  );
}

Extract OTP

function extractOTP(emailBody: string): string | null {
  const match = emailBody.match(/\b(\d{6})\b/);
  return match ? match[1] : null;
}

async function verifyOTP() {
  const email = await stamp0.waitForEmail({ inboxId: inbox.id });
  const otp = extractOTP(email.body);

  if (otp) {
    // Use OTP in your test
    console.log('OTP:', otp);
  }
}

REST API

If you need to use the API directly without the SDK, see the API Reference.

Next Steps

Playwright Guide - Using SDK with Playwright
Cypress Guide - Using SDK with Cypress
API Keys - Managing API access
MCP Server - Using with AI agents

SDK

On this page