mailmark

Deprecated: This package has been renamed to remindme-sdk. Please migrate to the new package — this one will no longer receive updates.

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

Installation

bun add mailmark
# or
npm install mailmark

Quick Start

import { Mailmark } from 'mailmark';

const client = new Mailmark('dm_live_your_api_key');

await client.send({
  from: '[email protected]',
  to: ['[email protected]'],
  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 [email protected]
  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 ("[email protected]").

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 ['[email protected]']
  emails: ['[email protected]', '[email protected]'],
});

| 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: ['[email protected]'],
  removeEmails: ['[email protected]'],
});

| 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: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  subject: 'Welcome',
  html: '<p>Hello!</p>',
});

// Campaign — one individual email per recipient, tracked under a shared batchId
await client.send({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]'],
  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: '[email protected]',
  to: '[email protected]',
  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';

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

cURL Reference

# List mailboxes
curl https://harmless-armadillo-386.convex.site/v1/mailboxes \
  -H "Authorization: Bearer dm_live_your_key"

# Send email
curl -X POST https://harmless-armadillo-386.convex.site/v1/send \
  -H "Authorization: Bearer dm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"from":"[email protected]","to":["[email protected]"],"subject":"Hello","html":"<p>Hello!</p>"}'

License

MIT