The Mailfully v1 API.

Authentication

Authenticate every request with your API key as a bearer token. The SDK sets this header for you from the apiKey you pass to the constructor; it never reads the environment and never logs the key. Keys are scoped to a single environment (test or live) — use a test key for the simulator path and a live key for real sends.

Authorization: Bearer mf_live_…

Idempotency

The send and batch mutations accept an Idempotency-Key header so a retry never sends twice. Replaying a request with a key the server has already seen returns the original 202 { id } — the same id, with no duplicate send. In the SDK, pass it as the second argument:

await mailfully.emails.send(input, { idempotencyKey: `welcome:${userId}` });

Choose a key that is stable for the logical operation — e.g. a key derived from the user and the email type — so a network retry of the same intent collapses to one send.

Errors

The API returns failures as a JSON envelope with a machine-readable type, a human message, and (for validation errors) the offending param.

{
  "error": {
    "type": "validation_error",
    "message": "subject is required",
    "param": "subject"
  }
}

The SDK surfaces this as the error arm of a { data, error } tuple — it never throws. Branch on error to narrow data to non-null on the success path:

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

// The SDK NEVER throws. On any failure — transport, non-2xx, or a parse
// error — `data` is null and `error` is a MailfullyError carrying the
// envelope fields plus the HTTP status (or null for a transport failure).
if (error) {
  console.error(error.type);       // e.g. "validation_error" (or null)
  console.error(error.message);    // human-readable message
  console.error(error.param);      // offending field (validation only)
  console.error(error.statusCode); // HTTP status, or null (transport)
} else {
  console.log(data.id);            // success — narrowed to non-null
}

Pagination

List endpoints are cursor-paginated. A page is { data, has_more, next_cursor }: when has_more is true, pass next_cursor as the next request’s cursor.

let cursor: string | undefined;

do {
  const { data, error } = await mailfully.emails.list({ limit: 100, cursor });
  if (error) throw error; // or handle it — your call
  for (const row of data.data) {
    console.log(row.id, row.last_event);
  }
  cursor = data.next_cursor ?? undefined;
} while (cursor); // `has_more` is true exactly while next_cursor is set

Send with a test-environment API key and every recipient is rewritten to the SES Mailbox Simulator (@simulator.amazonses.com) — no real mail is sent and no verified domain is needed. The recipient’s local-part selects the simulated outcome; any other local-part behaves like success. You can also address [email protected] and friends directly.

See the zero-to-send walkthrough for a runnable test send, or the quickstarts for full integration examples.