SDK Reference

# npm
npm install @mailloop/sdk

# yarn
yarn add @mailloop/sdk

# pnpm
pnpm add @mailloop/sdk

import { MailloopClient } from '@mailloop/sdk';

const client = new MailloopClient({
  apiKey: 'ml_live_your_api_key_here'
});

const sandbox = await client.sandboxes.create({
  name: 'my-sandbox'
});

const sandbox = await client.sandboxes.createTemporary({
  duration: 30,
  name: 'ci-test'
});

const { sandboxes } = await client.sandboxes.list();

const sandbox = await client.sandboxes.get('sandbox-id');

const updated = await client.sandboxes.update('sandbox-id', {
  name: 'renamed-sandbox'
});

await client.sandboxes.delete('sandbox-id');

const { emails, total } = await client.emails.list('sandbox-id', {
  limit: 10,
  offset: 0
});

for (const email of emails) {
  console.log(`${email.from}: ${email.subject}`);
}

const email = await client.emails.get('sandbox-id', 'email-id');

console.log(email.subject);
console.log(email.html);
console.log(email.headers);
console.log(email.attachments);

// Wait for any email
const email = await client.emails.waitFor('sandbox-id');

// Wait for an email from a specific sender
const email = await client.emails.waitFor('sandbox-id', {
  from: '[email protected]',
  timeout: 45000
});

// Wait for an email with a specific subject
const email = await client.emails.waitFor('sandbox-id', {
  subject: 'Password Reset'
});

import { TimeoutError } from '@mailloop/sdk';

try {
  const email = await client.emails.waitFor('sandbox-id', {
    subject: 'Welcome',
    timeout: 10000
  });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('No matching email arrived within 10 seconds');
  }
}

const result = await client.emails.send({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Your order has shipped',
  blocks: [
    { type: 'heading', content: 'Order Shipped', level: 2 },
    { type: 'paragraph', content: 'Your order #4821 is on its way.' },
    { type: 'button', text: 'Track Package', href: 'https://acme.com/track/4821' }
  ],
  layout: {
    primaryColor: '#4F46E5',
    companyName: 'Acme Inc.'
  }
});

console.log(result.id);     // Email ID
console.log(result.status); // "sent" or "failed"

interface Sandbox {
  id: string;
  name: string;
  username: string;
  password: string;
  emailAddress: string;   // [email protected]
  emailCount: number;
  isTemporary: boolean;
  deleteAfter: string | null; // ISO timestamp
  createdAt: string;          // ISO timestamp
  updatedAt: string;          // ISO timestamp
}

interface EmailSummary {
  id: string;
  from: string;
  to: string[];
  subject: string;
  preview: string;          // First 128 characters of plain text
  hasAttachments: boolean;
  receivedAt: string;       // ISO timestamp
}

interface EmailDetail {
  id: string;
  messageId: string;
  from: string;
  to: string[];
  cc: string[] | null;
  bcc: string[] | null;
  subject: string;
  text: string | null;
  html: string | null;
  headers: Record<string, string>;
  hasAttachments: boolean;
  attachments: EmailAttachment[];
  receivedAt: string;       // ISO timestamp
}

interface EmailAttachment {
  id: string;
  filename: string;
  contentType: string;
  size: number;             // Size in bytes
  checksum: string;
}

MailloopError (base class)
├── AuthenticationError  (401 - invalid or missing API key)
├── PermissionError      (403 - insufficient permissions)
├── NotFoundError        (404 - resource not found)
├── RateLimitError       (429 - too many requests)
├── TimeoutError         (waiting for email timed out)
└── ValidationError      (400 - invalid request data)

import {
  MailloopClient,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  TimeoutError,
  ValidationError,
} from '@mailloop/sdk';

const client = new MailloopClient({ apiKey: process.env.MAILLOOP_API_KEY });

try {
  const email = await client.emails.waitFor('sandbox-id', {
    subject: 'Welcome',
    timeout: 15000
  });
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('No email arrived in time');
  } else if (error instanceof AuthenticationError) {
    console.log('Check your API key');
  } else if (error instanceof NotFoundError) {
    console.log('Sandbox does not exist');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.log('Invalid parameters:', error.details);
  } else {
    throw error;
  }
}

Authorization: Bearer ml_live_your_api_key_here

https://api.mailloop.io/v1