JSPM

mailmark-sdk

0.2.0
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 4
    • Score
      100M100P100Q26773F
    • License MIT

    Official Node.js SDK for the Mailmark transactional email API

    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-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');

    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