@mailhooks/sdk v0.1.2

@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: 'sender@example.com',
    subject: 'Important',
    startDate: '2024-01-01',
    endDate: '2024-12-31',
  },
  sort: {
    field: 'createdAt',
    order: 'desc',
  },
});

Get Email

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

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

Types

The SDK includes comprehensive TypeScript types:

interface Email {
  id: string;
  from: string;
  to: string[];
  subject: string;
  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