Package Exports
- mailmark-sdk
Readme
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-sdkQuick 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');Emails
client.listEmails(options?)
List emails for a mailbox. Defaults to the first mailbox's inbox, 50 results.
const emails = await client.listEmails({
mailbox: 'hello@yourdomain.com',
folder: 'inbox',
limit: 25,
});
// [{ id, messageId, from, to, subject, snippet, folder, date, read, starred, ... }]| Field | Type | Default | Description |
|---|---|---|---|
mailbox |
string |
First mailbox | Mailbox address to list emails for |
folder |
"inbox" | "sent" | "outbox" | "drafts" | "trash" |
"inbox" |
Folder to list |
limit |
number |
50 |
Max results (up to 100) |
client.getEmail(id)
Get a single email by ID, including cc, bcc, and s3Key.
const email = await client.getEmail('emails:abc123');client.deleteEmail(id)
Delete an email. First call moves to trash; second call permanently deletes.
await client.deleteEmail('emails:abc123');
// { moved: "trash" } or { deleted: true }Contacts
client.listContacts()
Returns all contacts for the authenticated user.
const contacts = await client.listContacts();
// [{ id, email, name }, ...]client.createContact(options)
Create or update a contact.
await client.createContact({
email: 'jane@example.com',
name: 'Jane Smith',
});| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | Contact email address |
name |
string |
Yes | Contact display name |
client.deleteContact(id)
Delete a contact by ID.
await client.deleteContact('contacts:abc123');Sequences
Sequences are automated multi-step email flows with configurable delays.
client.listSequences()
Returns all sequences for the domain with enrollment stats.
const sequences = await client.listSequences();
// [{ id, name, status, steps, mailboxAddress, stats, createdAt }]client.createSequence(options)
Create a new sequence. The first step must be send_email.
const sequence = await client.createSequence({
name: 'Welcome Series',
from: 'hello@yourdomain.com',
steps: [
{ type: 'send_email', subject: 'Welcome {{firstName}}', html: '<p>Hello!</p>' },
{ type: 'delay', delayMs: 86400000 }, // 1 day
{ type: 'send_email', subject: 'Follow up', html: '<p>Checking in</p>' },
],
});| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Sequence name |
from |
string |
Yes | Sender mailbox address |
steps |
SequenceStep[] |
Yes | Array of send_email and delay steps |
client.pauseSequence(id)
Pause an active sequence.
await client.pauseSequence('sequences:abc123');client.resumeSequence(id)
Resume a paused sequence.
await client.resumeSequence('sequences:abc123');client.deleteSequence(id)
Cancel a sequence and all active enrollments.
const result = await client.deleteSequence('sequences:abc123');
// { id, status: "completed", cancelledEnrollments: 42 }client.enrollContacts(sequenceId, options)
Enroll contacts into a sequence. Max 100 per request.
const result = await client.enrollContacts('sequences:abc123', {
contacts: [
{ email: 'jane@example.com', mergeFields: { firstName: 'Jane', company: 'Acme' } },
{ email: 'bob@example.com', mergeFields: { firstName: 'Bob' } },
],
});
// { enrolled: 2, skipped: 0, enrollmentIds: [...] }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>"}'
# List emails (inbox)
curl "https://api.mailmark.dev/v1/emails?mailbox=hello@yourdomain.com&folder=inbox&limit=25" \
-H "Authorization: Bearer dm_live_your_key"
# List contacts
curl https://api.mailmark.dev/v1/contacts \
-H "Authorization: Bearer dm_live_your_key"
# Create a sequence
curl -X POST https://api.mailmark.dev/v1/sequences \
-H "Authorization: Bearer dm_live_your_key" \
-H "Content-Type: application/json" \
-d '{"name":"Welcome","from":"hello@yourdomain.com","steps":[{"type":"send_email","subject":"Welcome","html":"<p>Hi!</p>"},{"type":"delay","delayMs":86400000},{"type":"send_email","subject":"Follow up","html":"<p>Checking in</p>"}]}'
# Enroll contacts
curl -X POST https://api.mailmark.dev/v1/sequences/SEQUENCE_ID/enroll \
-H "Authorization: Bearer dm_live_your_key" \
-H "Content-Type: application/json" \
-d '{"contacts":[{"email":"jane@example.com","mergeFields":{"firstName":"Jane"}}]}'License
MIT