mailmark

Official Node.js SDK for the Mailmark transactional email API.

Installation

bun add mailmark-sdk
# or
pnpm add mailmark-sdk
# or
npm install mailmark-sdk

Quick Start

import { Mailmark } from 'mailmark-sdk';

const client = new Mailmark('dm_live_your_api_key');

await client.send({
  from: 'hello@yourdomain.com',
  to: ['recipient@example.com'],
  subject: 'Hello from Mailmark',
  html: '<h1>Hello!</h1><p>This email was sent via the Mailmark API.</p>',
});

API Reference

`new Mailmark(apiKey, options?)`

Parameter	Type	Description
`apiKey`	`string`	Your API key from the Mailmark Developer dashboard
`options.baseUrl`	`string`	Override the API base URL (for self-hosted instances)

Mailboxes

`client.listMailboxes()`

Returns all mailboxes on the API key's domain.

const mailboxes = await client.listMailboxes();
// [{ id, address, fullAddress, displayName }, ...]

`client.createMailbox(options)`

Creates a new mailbox. Pass only the local part of the address — the domain is appended automatically.

const mailbox = await client.createMailbox({
  address: 'support',       // becomes support@yourdomain.com
  displayName: 'Support Team',
});

Field	Type	Required	Description
`address`	`string`	Yes	Local part of the address (e.g. `support`)
`displayName`	`string`	No	Optional sender display name

`client.deleteMailbox(address)`

Deletes a mailbox and all its emails. Pass either the local part ("support") or the full address ("support@yourdomain.com").

await client.deleteMailbox('support');

Sender Groups

Sender groups define which mailboxes send to which recipient lists.

`client.listSenderGroups()`

Returns all sender groups on the API key's domain.

const groups = await client.listSenderGroups();
// [{ id, name, mailboxIds, emails }, ...]

`client.createSenderGroup(options)`

Creates a new sender group.

const group = await client.createSenderGroup({
  name: 'Newsletter',
  mailboxes: 'all',                          // or ['hello@yourdomain.com']
  emails: ['alice@example.com', 'bob@example.com'],
});

Field	Type	Required	Description
`name`	`string`	Yes	Group name
`mailboxes`	`string[] \| "all"`	No	Sender mailbox addresses. Defaults to `"all"`
`emails`	`string[]`	No	Initial recipient list

`client.updateSenderGroup(id, options)`

Updates a sender group. All fields are optional.

await client.updateSenderGroup('group_id', {
  name: 'Newsletter v2',
  addEmails: ['carol@example.com'],
  removeEmails: ['bob@example.com'],
});

Field	Type	Description
`name`	`string`	Rename the group
`emails`	`string[]`	Replace the entire recipient list
`addEmails`	`string[]`	Add emails to the recipient list
`removeEmails`	`string[]`	Remove emails from the recipient list
`mailboxes`	`string[] \| "all"`	Replace the sender mailbox list

`client.deleteSenderGroup(id)`

Deletes a sender group by ID.

await client.deleteSenderGroup('group_id');

Send Email

`client.send(options)`

Sends an email from a mailbox on the API key's domain.

// Transactional (default) — one email to all recipients together
await client.send({
  from: 'hello@yourdomain.com',
  to: ['alice@example.com', 'bob@example.com'],
  subject: 'Welcome',
  html: '<p>Hello!</p>',
});

// Campaign — one individual email per recipient, tracked under a shared batchId
await client.send({
  from: 'hello@yourdomain.com',
  to: ['alice@example.com', 'bob@example.com'],
  subject: 'Our newsletter',
  html: '<p>This month in Mailmark...</p>',
  type: 'campaign',
});

// Scheduled — send at a future time (Unix ms timestamp)
await client.send({
  from: 'hello@yourdomain.com',
  to: 'alice@example.com',
  subject: 'Reminder',
  text: 'Just a reminder!',
  scheduledAt: Date.now() + 60 * 60 * 1000, // 1 hour from now
});

Field	Type	Required	Description
`from`	`string`	Yes	Sender address — must be an existing mailbox on the domain
`to`	`string \| string[]`	Yes	One or more recipient addresses
`subject`	`string`	Yes	Email subject line
`html`	`string`	One of	HTML email body
`text`	`string`	One of	Plain-text body (used when `html` is not provided)
`type`	`"transactional" \| "campaign"`	No	Defaults to `"transactional"`
`scheduledAt`	`number`	No	Future Unix ms timestamp to schedule the send

Returns Promise<SendEmailResult>:

Field	Description
`messageId`	Present for transactional sends
`messageIds`	Present for campaign sends (one per recipient)
`batchId`	Present for campaign sends
`status`	`"queued"` or `"scheduled"`

Error Handling

All API errors throw a MailmarkError with:

.message — human-readable error description
.status — HTTP status code
.response — parsed response body

import { Mailmark, MailmarkError } from 'mailmark-sdk';

try {
  await client.send({ ... });
} catch (err) {
  if (err instanceof MailmarkError) {
    console.error(err.status, err.message);
  }
}

cURL Reference

# List mailboxes
curl https://api.mailmark.dev/v1/mailboxes \
  -H "Authorization: Bearer dm_live_your_key"

# Send email
curl -X POST https://api.mailmark.dev/v1/send \
  -H "Authorization: Bearer dm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"from":"hello@yourdomain.com","to":["recipient@example.com"],"subject":"Hello","html":"<p>Hello!</p>"}'

License

MIT