@mailhooks/sdk

TypeScript SDK for the Mailhooks API. Easily integrate email receiving capabilities into your applications.

Installation

npm install @mailhooks/sdk
# or
yarn add @mailhooks/sdk
# or
pnpm add @mailhooks/sdk

Quick Start

import { Mailhooks } from '@mailhooks/sdk';

// Initialize the SDK with your API key
const mailhooks = new Mailhooks({
  apiKey: 'your-api-key-here',
  // baseUrl: 'https://custom-url.com/api', // optional, defaults to https://mailhooks.dev/api
});

// Get all emails
const emails = await mailhooks.emails.list();
console.log(emails.data);

// Get a specific email
const email = await mailhooks.emails.getEmail('email-id');
console.log(email);

// Get email content
const content = await mailhooks.emails.getContent('email-id');
console.log(content.html, content.text);

API Reference

Authentication

The SDK uses API key authentication. You can create API keys in your Mailhooks dashboard.

const mailhooks = new Mailhooks({
  apiKey: 'your-api-key',
  // baseUrl: 'https://custom-url.com/api', // optional, defaults to https://mailhooks.dev/api
});

Emails

List Emails

const emails = await mailhooks.emails.list({
  page: 1,
  perPage: 20,
  filter: {
    from: '[email protected]',
    subject: 'Important',
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    read: false, // Filter by read status
  },
  sort: {
    field: 'createdAt',
    order: 'desc',
  },
});

Get Email

// Get email without marking as read
const email = await mailhooks.emails.getEmail('email-id');

// Get email and mark it as read in one call
const readEmail = await mailhooks.emails.getEmail('email-id', true);

Get Email Content

const content = await mailhooks.emails.getContent('email-id');

Download Email as EML

const emlFile = await mailhooks.emails.downloadEml('email-id');
// emlFile.data contains the ArrayBuffer
// emlFile.filename contains the suggested filename

Download Attachment

const attachment = await mailhooks.emails.downloadAttachment('email-id', 'attachment-id');
// attachment.data contains the ArrayBuffer
// attachment.filename contains the original filename
// attachment.contentType contains the MIME type

Mark Email as Read/Unread

// Mark email as read
const readEmail = await mailhooks.emails.markAsRead('email-id');
console.log(readEmail.read); // true

// Mark email as unread
const unreadEmail = await mailhooks.emails.markAsUnread('email-id');
console.log(unreadEmail.read); // false

Wait for Email

Wait for an email that matches specific filters. Useful for testing and automation.

// Basic usage - wait for unread email from specific sender
const email = await mailhooks.emails.waitFor({
  filter: { 
    from: '[email protected]',
    read: false // Only wait for unread emails
  },
  timeout: 30000, // 30 seconds
  pollInterval: 2000, // Check every 2 seconds
});

// Advanced usage with all options
const email = await mailhooks.emails.waitFor({
  filter: {
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Order Confirmation',
    read: false, // Only unread emails
  },
  lookbackWindow: 10000, // Only consider emails from last 10 seconds
  initialDelay: 5000,    // Wait 5 seconds before first check
  timeout: 60000,        // Total timeout of 60 seconds
  pollInterval: 3000,    // Check every 3 seconds
  maxRetries: 20,        // Stop after 20 attempts
});

Options:

• filter: Same filters as list() method (from, to, subject, startDate, endDate, read)
• lookbackWindow: How far back to look for emails on first check (default: 10000ms)
• initialDelay: Delay before starting to poll (default: 0ms)
• timeout: Maximum time to wait before throwing error (default: 30000ms)
• pollInterval: Time between checks (default: 1000ms)
• maxRetries: Maximum number of polling attempts (default: unlimited)

Key Features:

• Returns immediately if a matching email already exists (within lookback window)
• Prevents returning old emails by using the lookback window
• Efficiently tracks checked emails to avoid duplicates
• Throws error on timeout or max retries exceeded

Types

The SDK includes comprehensive TypeScript types:

interface Email {
  id: string;
  from: string;
  to: string[];
  subject: string;
  read: boolean;
  createdAt: Date;
  attachments: Attachment[];
}

interface EmailContent {
  html?: string;
  text?: string;
}

interface Attachment {
  id: string;
  filename: string;
  contentType: string;
  size: number;
}

Error Handling

The SDK throws standard HTTP errors. Wrap your calls in try-catch blocks:

try {
  const email = await mailhooks.emails.getEmail('non-existent-id');
} catch (error) {
  if (error.response?.status === 404) {
    console.log('Email not found');
  } else if (error.response?.status === 403) {
    console.log('Authentication failed - check your API key');
  }
}

Common Errors

• 403 Forbidden: Invalid API key or missing authentication
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded

License

MIT