Mailry SDK for JavaScript & TypeScript

The official Node.js and TypeScript client for the Mailry.co public API. Send email from your mailboxes, read and manage the messages they hold, upload attachments and look up your domains and email accounts.

• Written in TypeScript, with full type definitions
• Works with ESM and CommonJS
• No runtime dependencies (uses the native fetch, FormData and Blob)
• Automatic retries with backoff for rate limits and transient errors
• Typed errors for every failure mode

Requirements

Node.js 18 or later. It also runs on Bun, Deno and edge runtimes that provide fetch.

Installation

npm install mailry
# or
pnpm add mailry
# or
yarn add mailry
# or
bun add mailry

Quick start

Create an API key in the Mailry dashboard, then:

import { Mailry } from 'mailry';

const mailry = new Mailry('your_api_key');

const { data: accounts } = await mailry.emailAccounts.list();

await mailry.inbox.send({
  emailId: accounts[0].id,
  to: '[email protected]',
  subject: 'Hello from Mailry',
  plainBody: 'Hello!',
  htmlBody: '<p>Hello!</p>',
});

CommonJS:

const { Mailry } = require('mailry');

If you leave out the API key, the client reads it from the MAILRY_API_KEY environment variable:

const mailry = new Mailry();

Keep your API key on the server. Never ship it in browser code.

Configuration

const mailry = new Mailry({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.mailry.co',
  timeout: 60_000,
  maxRetries: 2,
  headers: { 'X-Request-Source': 'billing-service' },
  fetch: customFetch,
});

Option	Default	Description
apiKey	process.env.MAILRY_API_KEY	Your Mailry API key
baseUrl	process.env.MAILRY_BASE_URL or https://api.mailry.co	API base URL, for example http://localhost:4000
timeout	60000	Request timeout in milliseconds
maxRetries	2	Retries for rate limited or transient failures
headers	{}	Extra headers sent with every request
fetch	globalThis.fetch	Custom fetch implementation

Every method also takes an optional last argument to override these per request:

const controller = new AbortController();

await mailry.domains.list({}, { timeout: 5_000, maxRetries: 0, signal: controller.signal });

Usage

Send an email

POST /public/inbox/send

const result = await mailry.inbox.send({
  emailId: 'b3f1c2d4-...',
  to: ['[email protected]', 'John <[email protected]>'],
  subject: 'Weekly report',
  plainBody: 'The report is attached.',
  htmlBody: '<p>The report is attached.</p>',
});

console.log(result.message);

Field	Type	Required	Description
emailId	string	Yes	ID of the mailbox you send from (see emailAccounts.list())
to	string | string[]	Yes	Recipients, up to 50 per request
cc	string | string[]	No	Carbon copy recipients
subject	string	Yes	Subject line
plainBody	string	One of	Plain text body
htmlBody	string	One of	HTML body
attachments	Attachment[]	No	Up to 10 files, 5MB each: doc, docx, pdf, xlsx, xls, txt

At least one of plainBody or htmlBody is required. Each call counts against your daily API send quota.

Attachments

An attachment is either a File or an object with a filename and content. content can be a Buffer, Uint8Array, ArrayBuffer, Blob or string. The content type is inferred from the file extension unless you set contentType.

import { readFile } from 'node:fs/promises';

await mailry.inbox.send({
  emailId,
  to: '[email protected]',
  subject: 'Your invoice',
  htmlBody: '<p>Your invoice is attached.</p>',
  attachments: [
    { filename: 'invoice.pdf', content: await readFile('./invoice.pdf') },
    { filename: 'notes.txt', content: 'Thanks for your business!' },
    { filename: 'data.xlsx', content: spreadsheetBuffer, contentType: 'application/vnd.ms-excel' },
  ],
});

Upload an attachment

POST /public/inbox/upload-attachment

Upload an office document (doc, docx, xls, xlsx, ppt, pptx, pdf, up to 25MB) ahead of time and get back its ID.

const { data } = await mailry.inbox.uploadAttachment({
  filename: 'contract.pdf',
  content: await readFile('./contract.pdf'),
});

console.log(data.id, data.fileName, data.fileSize);

List messages

GET /public/inbox

Messages come newest first, one row per conversation. With search, which matches subject, sender and body, each matching message is returned on its own.

This is the beginning of the README. Read the rest at the original. Read the full README ↗