Node.js SDK

@mailfully/node is a typed wrapper over the global fetch API. It has zero runtime dependencies, ships as ESM only (no CommonJS build), and requires Node.js 24 or later.

Install

npm install @mailfully/node

Also works with pnpm add @mailfully/node or yarn add @mailfully/node.

Create a client

import { Mailfully } from "@mailfully/node";

const mailfully = new Mailfully({
  apiKey: process.env.MAILFULLY_API_KEY ?? "",
});

The SDK never reads environment variables itself and never logs the key. Pass it explicitly. Set it in your shell:

export MAILFULLY_API_KEY=mf_live_xxxxxxxxxxxx

The constructor TypeError is the only exception the SDK ever throws. Every method returns a result tuple instead.

Resources hang off the client instance: mailfully.emails, mailfully.domains, mailfully.apiKeys, mailfully.webhooks, mailfully.suppressions, and mailfully.analytics. The resource classes are not exported. Reach them through the client.

Handle results

Every method resolves to a { data, error } tuple. Exactly one side is non-null:

type MailfullyResult<T> =
  | { data: T; error: null }
  | { data: null; error: MailfullyError };

Check error !== null before touching data, and TypeScript narrows the other side for you:

const { data, error } = await mailfully.emails.send({
  from: "orders@mail.acme.com",
  to: "you@yourcompany.com", // replace with an address you own — example.com bounces
  subject: "Your order shipped",
  html: "<p>Your order is on its way.</p>",
  tags: [{ name: "category", value: "order-shipped" }],
});

if (error !== null) {
  if (error.statusCode === null) {
    // The request never reached the API: DNS failure, connection reset, abort.
    // The underlying fetch error is on error.cause.
    console.error(`Network failure: ${error.message}`);
  } else {
    // The API responded with a non-2xx status.
    console.error(
      `Send failed (${error.statusCode} ${error.type}): ${error.message}`,
    );
  }
  return;
}

console.log(data.id); // "01J9ZC3AB8XQ4RW2N7VKT5EMHD" — a bare ULID, no prefix

MailfullyError

MailfullyError extends Error:

Non-2xx responses are parsed from the API's canonical envelope { error: { type, message, param } }. A 2xx response with an empty or non-JSON body resolves with data: null rather than an error (relevant for 204-style responses).

The SDK does not validate response bodies at runtime; success payloads are cast to the documented types. See Errors for the full catalog of error type values.

Methods

The SDK exposes 27 methods across six resources. Each maps to exactly one endpoint.

emails

emails.list accepts { limit, cursor, status, domain, tag, recipient, from, to }. emails.reschedule takes { scheduledAt }, sent on the wire as scheduled_at.

domains

domains.create takes { name, mailFromPrefix? }; domains.tracking takes { enabled: boolean }.

apiKeys

Session-only today. See the warning above.

webhooks

Session-only today. See the warning above.

webhooks.create takes { url, events }, where events is a subset of the event types exported as MAILFULLY_EVENT_TYPES. The filter accepts email.suppressed, but that type is never delivered as a webhook today. See Webhooks.

suppressions

suppressions.list works with the read:suppressions scope; create and delete are session-only today (see the warning above).

suppressions.list accepts { limit, cursor, email, reason }; email is an exact match.

analytics

The rollup queries take { from, to } as YYYY-MM-DD days, plus domain or tag on the respective endpoints. Every rollup row carries the counters sent, delivered, bounced, complained, opened, clicked.

Idempotency keys

emails.send and emails.batch accept an options bag as their second argument. Set idempotencyKey and the SDK forwards it as the Idempotency-Key header. Repeating the request with the same key returns the original result instead of sending twice:

const { data, error } = await mailfully.emails.send(input, {
  idempotencyKey: crypto.randomUUID(),
});

No other method takes request options. See Idempotency for key constraints and replay semantics.

Field naming

Inputs are camelCase; the SDK maps them to the API's snake_case wire fields and drops omitted optionals entirely (it never sends null):

Responses are not camelized: you get the raw snake_case wire shapes (created_at, last_event, has_more, next_cursor, …). The one exception is analytics.externalReputation(), whose payload is camelCase on the wire itself (gmailSpamRate, observedAt, worstGmailSpamRate).

What the SDK doesn't cover

• No templates resource. Template sending works — pass template: { id: "tmpl_...", variables: { ... } } to emails.send. Template management (create, update, delete) goes through the API directly.
• No webhooks.get(id). GET /v1/webhooks/:id exists in the API but has no SDK method.
• No dead-letter methods. GET /v1/webhook-dead-letters and POST /v1/webhook-dead-letters/:id/replay have no SDK methods.
• No signature-verification helper. The SDK exports the event-type constants only; verify inbound webhook signatures yourself (see the webhooks guide).
• No automatic retries, timeouts, or pagination. Each call is a single fetch with no retry, no timeout or AbortSignal option, and no auto-pagination. Loop on next_cursor yourself.