@studioelxr/mail-sdk

Thin, provider-agnostic TypeScript HTTP client for the Elixir Mail transactional email API. Client websites use it to send email through a centrally managed Elixir Mail instance — no Resend credentials, no database access, no template HTML.

Install

npm install @studioelxr/mail-sdk

Usage

import { ElixirMail } from "@studioelxr/mail-sdk";

const mail = new ElixirMail({
  apiKey: process.env.ELIXIR_MAIL_KEY,
  // baseUrl: "https://mail.example.com",   // defaults to http://localhost:3000
});

await mail.send({
  template: "contact-submission-confirmation",
  data: {
    name: "Jane",
    email: "[email protected]",
    message: "Hello",
  },
  to: "[email protected]",
  replyTo: "[email protected]",
});

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Elixir Mail API key for this client (required). | | baseUrl | string | http://localhost:3000 | Base URL of the Elixir Mail API. | | timeoutMs | number | 10000 | Request timeout in milliseconds. | | fetch | typeof fetch | global fetch | Custom fetch implementation. |

send() request

| Field | Type | Notes | |-------|------|-------| | template | string | Centrally managed template key (exclusive with html). | | data | Record<string, unknown> | Data rendered into the template. | | html | string | Raw HTML body for direct sends (used by the Payload adapter). | | subject | string | Subject for raw sends (or to override a template subject). | | text | string | Plain-text body for raw sends. | | to | string \| string[] | Recipient(s). | | replyTo | string \| string[] | Reply-To header address(es). | | sender | string | Configured sender key or email; defaults to the template/client sender. | | idempotencyKey | string | Identical keys within a client never send twice. |

Response

{
  success: true,
  emailLogId: "c6264901-...",
  provider: "resend",
  providerMessageId: "d871ebc8-...",
  status: "sent",
  replayed: false,   // true when served from a previous identical request
}

Errors

Throws typed errors:

• ElixirMailError — base error with a code (TIMEOUT, NETWORK_ERROR, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, SERVER_ERROR, API_ERROR).
• ElixirMailApiError — a structured error returned by the API, carrying the server error code (e.g. TEMPLATE_NOT_FOUND) plus status and details.

import { ElixirMailApiError } from "@studioelxr/mail-sdk";

try {
  await mail.send({ template: "missing", data: {}, to: "[email protected]" });
} catch (error) {
  if (error instanceof ElixirMailApiError) {
    console.log(error.apiCode, error.status, error.details);
  }
}

License

MIT