SandMail — Disposable Email API for AI Agents

Create temporary inboxes, extract OTP codes, and receive webhooks — in 3 lines of code.

Install

npm install sandmail

Quick Start

const { SandMail } = require('sandmail');
const client = new SandMail('sk_live_your_api_key');

// Create inbox → wait for OTP → done
const inbox = await client.createInbox();
const otp = await client.waitForOTP(inbox.email, { timeout: 30 });
console.log(otp.code); // "847291"

Features

• Instant inboxes — Create disposable emails on 7 domains
• OTP extraction — Auto-detect verification codes from emails
• Wait endpoints — Long-poll until an email arrives (no polling loops)
• Webhooks — Get notified in real-time when emails arrive
• Email forwarding — Forward to your real email via @sandtobox.com
• Multi-domain — Rotate across 7 domains to avoid blocking

Usage

Create an Inbox

const inbox = await client.createInbox({
  domain: 'tempyx.com',       // optional
  customLocal: 'mytest',      // optional → [email protected]
  ttlHours: 1,                // optional, default 24
});
console.log(inbox.email); // "[email protected]"

Wait for OTP (recommended)

One call that waits for an email and extracts the OTP:

const result = await client.waitForOTP(inbox.email, { timeout: 30 });

if (result.found) {
  console.log(result.code);       // "847291"
  console.log(result.confidence); // "high"
} else {
  // No OTP found — check result.body_text for raw email content
  console.log(result.body_text);
}

Extract OTP from Existing Email

const otp = await client.getOTP(inbox.email);
// otp.code, otp.type ("numeric_6"), otp.confidence ("high"/"medium")

// Include raw body as fallback:
const otp = await client.getOTP(inbox.email, { includeBody: true });
console.log(otp.body_text); // plain text email body

Wait for Any Email

const result = await client.waitForEmail(inbox.email, {
  timeout: 30,
  extractOtp: true, // also extract OTP from the email
});

if (result.arrived) {
  console.log(result.new_emails[0].subject);
  console.log(result.otp?.code); // if extractOtp was true
}

Read Emails

const emails = await client.getEmails(inbox.email);
const latest = await client.getLatestEmail(inbox.email);
const fresh = await client.getNewEmails(inbox.email, '2026-04-14 10:00:00 +0000');

Webhooks

// Register
const wh = await client.createWebhook('https://myapp.com/webhook');
console.log(wh.secret); // use to verify HMAC signatures

// List
const webhooks = await client.listWebhooks();

// Delete
await client.deleteWebhook(wh.webhook_id);

Forwarding

const fwd = await client.createForward({ customLocal: 'alerts' });
// fwd.alias_email = "[email protected]"
// Emails to [email protected] → forwarded to your account email

Quota

const quota = await client.getQuota();
// { used: 42, limit: 1000, remaining: 958 }

Cleanup

await client.deleteInbox(inbox.email);

Configuration

const client = new SandMail({
  apiKey: 'sk_live_xxx',
  baseUrl: 'https://api.sandmail.dev/v1', // default
  timeout: 65, // seconds, default
});

Links

• Documentation
• Get API Key
• GitHub