Skip to main content

​
SDK Reference

Full API reference for zerodrop-client.

​
Installation

npm install zerodrop-client

​
ZeroDrop class

import { ZeroDrop } from 'zerodrop-client';

const mail = new ZeroDrop(apiKey?, options?);

​
Parameters

ParameterTypeDescription
apiKeystring (optional)API key for Workspaces tier
options.baseUrlstring (optional)Custom base URL for self-hosted instances
Without an API key, ZeroDrop runs in free sandbox mode with a shared domain and 30-minute TTL.

​
generateInbox()

mail.generateInbox(): string
Generates a unique inbox address instantly. No network request. 
const inbox = mail.generateInbox();
// "swift-x7k2m@zerodrop-sandbox.online"

​
waitForLatest()

mail.waitForLatest(inbox: string, options?): Promise<ZeroDropEmail>
Waits for an email to arrive. Uses SSE for sub-second delivery, falls back to polling automatically. Throws ZeroDropTimeoutError if no email arrives within the timeout.

​
Options

OptionTypeDefaultDescription
timeoutnumber10000Milliseconds to wait
pollIntervalnumber2000Milliseconds between polls (fallback mode)
ssebooleantrueUse SSE for delivery
// Default — SSE, 10s timeout
const email = await mail.waitForLatest(inbox);

// Custom timeout
const email = await mail.waitForLatest(inbox, { timeout: 30000 });

// Force polling
const email = await mail.waitForLatest(inbox, { sse: false });

​
fetchLatest()

mail.fetchLatest(inbox: string): Promise<ZeroDropEmail | null>
Fetches the latest email without waiting. Returns null if the inbox is empty. 
const email = await mail.fetchLatest(inbox);
if (email) {
  console.log(email.subject);
}

​
ZeroDropEmail type

interface ZeroDropEmail {
  id: string;           // Unique message ID
  from: string;         // Sender address
  to: string;           // Recipient address
  subject: string;      // Email subject
  body: string;         // Parsed plain-text body
  rawBody: string;      // Full raw MIME message
  receivedAt: Date;     // UTC timestamp
  otp: string | null;   // Auto-extracted OTP code (4-8 digits)
  magicLink: string | null; // Auto-extracted verification/reset link
}

​
otp

4-8 digit numeric code extracted from the email body. Detected near labels like code, otp, pin, verification. null if not detected. 
const email = await mail.waitForLatest(inbox);
console.log(email.otp); // "123456" or null
Verification or reset URL extracted from the email body. Detected for URLs containing verify, confirm, reset, token, activate, or auth. null if not detected. 
console.log(email.magicLink); // "https://app.com/verify?token=abc" or null

​
Error types

​
ZeroDropTimeoutError

Thrown when no email arrives within the timeout. 
import { ZeroDropTimeoutError } from 'zerodrop-client';

try {
  const email = await mail.waitForLatest(inbox, { timeout: 10000 });
} catch (err) {
  if (err instanceof ZeroDropTimeoutError) {
    console.log('No email received in time');
  }
}

​
ZeroDropNetworkError

Thrown when the API is unreachable. Includes a link to the status page. 
import { ZeroDropNetworkError } from 'zerodrop-client';

try {
  const email = await mail.fetchLatest(inbox);
} catch (err) {
  if (err instanceof ZeroDropNetworkError) {
    console.log('Network error — check https://zerodrop.instatus.com');
  }
}

​
ZeroDropAuthError

Thrown when an invalid API key is provided.

​
Zero telemetry

The SDK does not send analytics, usage metrics, or environment data to any server. The only network requests made are explicit inbox polls to zerodrop.dev/api/inbox/{name}. Your CI pipeline is your business.