retransmit.dev 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,9 @@
 # retransmit.dev
 
+[![CI](https://github.com/retransmit-dev/retransmit-node/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/retransmit-dev/retransmit-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/retransmit.dev)](https://www.npmjs.com/package/retransmit.dev)
+[![license](https://img.shields.io/npm/l/retransmit.dev)](https://github.com/retransmit-dev/retransmit-node/blob/main/LICENSE)
+
 Node.js SDK for the [Retransmit](https://retransmit.dev) messaging API. Send email, SMS, and WhatsApp through one typed client. Zero dependencies, works on Node 18+ and edge runtimes with `fetch`.
 
 | Channel | SDK namespace | Availability |
@@ -74,6 +78,103 @@ Names and values allow letters, digits, underscores and dashes, up to 256
 characters each. Names must be unique within one email. Batch emails accept
 the same `tags` field.
 
+### Custom headers
+
+Add your own message headers with `headers`. The common case is a unique
+`X-Entity-Ref-ID` per email so Gmail does not thread related messages, such as
+order updates with the same subject, into one conversation.
+
+```ts
+await retransmit.emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Your order shipped",
+  html: "<p>Order #4821 is on its way.</p>",
+  headers: { "X-Entity-Ref-ID": "order_4821" },
+});
+```
+
+Up to 20 headers per email. Names are printable ASCII without `:` and may
+only appear once; values are a single line. Headers Retransmit sets itself,
+like `From`, `To`, `Subject`, `Date` or `Message-ID`, are rejected with a
+`validation_error`. Marketing emails keep the hosted `List-Unsubscribe`
+headers even if you pass your own. Headers come back on `emails.get`, and
+batch emails accept the same field.
+
+### Attachments
+
+Attach up to 20 files, 30 MB in total. Pass the bytes as `content` (a
+`Buffer`, `Uint8Array` or base64 string), or a public URL as `path` and
+Retransmit fetches it while the request runs. Either way the file travels
+inside the email.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+await retransmit.emails.send({
+  from: "Acme <billing@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Your invoice",
+  html: "<p>Your invoice is attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", content: await readFile("./invoice.pdf") },
+    { filename: "terms.pdf", path: "https://yourdomain.com/terms.pdf" },
+  ],
+});
+```
+
+To embed an image in the HTML, give it a `contentId` and reference it as
+`cid:`:
+
+```ts
+await retransmit.emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Welcome",
+  html: '<p><img src="cid:logo" alt="Acme" /> Glad to have you.</p>',
+  attachments: [{ filename: "logo.png", path: "https://yourdomain.com/logo.png", contentId: "logo" }],
+});
+```
+
+Executables, scripts and installers are rejected with `invalid_attachment`,
+and `batch.send` does not accept attachments. Files are kept for 30 days so
+you can see what went out:
+
+```ts
+const { data } = await retransmit.emails.attachments("em_xxxxxxxxxxxx");
+// data.attachments: [{ id, filename, content_type, size, download_url, expires_at, ... }]
+```
+
+`download_url` is signed and valid for one hour; it is `null` once the file
+has expired.
+
+### Idempotency
+
+A send can succeed on the server and still fail on your side, through a
+timeout or a dropped connection. Retrying it blindly sends the email twice.
+Pass an `idempotencyKey` and retries become safe: for 24 hours the same key
+with the same payload returns the original response, `id` included, and
+nothing is queued again.
+
+```ts
+await retransmit.emails.send(
+  {
+    from: "Acme <hello@yourdomain.com>",
+    to: "user@example.com",
+    subject: "Welcome to Acme",
+    html: "<p>Glad to have you.</p>",
+  },
+  { idempotencyKey: "welcome-user/123" },
+);
+```
+
+Use a value that identifies that exact email, such as a UUID or
+`<event>/<entity-id>`. Keys are 1 to 256 characters and are shared by every
+API key in your organization. The same key with a different payload returns
+`invalid_idempotent_request`; a retry that overlaps the first request returns
+`concurrent_idempotent_requests`, so wait a moment and try again. Batches
+accept the same option with one key for the whole batch.
+
 ### List and filter emails
 
 `emails.list` returns your emails newest first. Every tag you pass must match.
@@ -133,10 +234,13 @@ console.log(data?.status); // "sent" | "delivered" | "undelivered" | ...
 Send up to 10,000 emails in one request:
 
 ```ts
-const { data: batch } = await retransmit.batch.send([
-  { from: "Acme <hello@yourdomain.com>", to: "a@example.com", subject: "Hi", text: "Hello A" },
-  { from: "Acme <hello@yourdomain.com>", to: "b@example.com", subject: "Hi", text: "Hello B" },
-]);
+const { data: batch } = await retransmit.batch.send(
+  [
+    { from: "Acme <hello@yourdomain.com>", to: "a@example.com", subject: "Hi", text: "Hello A" },
+    { from: "Acme <hello@yourdomain.com>", to: "b@example.com", subject: "Hi", text: "Hello B" },
+  ],
+  { idempotencyKey: "weekly-digest/2026-09-07" },
+);
 
 const { data: progress } = await retransmit.batch.get(batch!.id);
 console.log(progress?.processed, "/", progress?.total, progress?.counts);

package/dist/index.cjs

@@ -32,6 +32,24 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/emails.ts
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function toWireAttachment(attachment) {
+  return {
+    filename: attachment.filename,
+    content: attachment.content === void 0 || typeof attachment.content === "string" ? attachment.content : toBase64(attachment.content),
+    path: attachment.path,
+    content_type: attachment.contentType,
+    content_id: attachment.contentId
+  };
+}
 function toWirePayload(options) {
   return {
     from: options.from,
@@ -43,7 +61,9 @@ function toWirePayload(options) {
     html: options.html,
     text: options.text,
     marketing: options.marketing,
-    tags: options.tags
+    tags: options.tags,
+    headers: options.headers,
+    attachments: options.attachments?.map(toWireAttachment)
   };
 }
 var Emails = class {
@@ -51,9 +71,18 @@ var Emails = class {
     this.client = client;
   }
   client;
-  /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-  send(options) {
-    return this.client.request("POST", "/v1/emails", toWirePayload(options));
+  /**
+   * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+   * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+   */
+  send(options, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails",
+      toWirePayload(options),
+      void 0,
+      requestOptions
+    );
   }
   /** Retrieves an email with its current status and event history. */
   get(id) {
@@ -76,6 +105,21 @@ var Emails = class {
   tags() {
     return this.client.request("GET", "/v1/emails/tags");
   }
+  /**
+   * The attachments of an email, each with a signed `download_url` valid for
+   * one hour. Files are kept for 30 days after the send; after that the link
+   * is `null` and only the metadata remains.
+   */
+  attachments(emailId) {
+    return this.client.request("GET", `/v1/emails/${encodeURIComponent(emailId)}/attachments`);
+  }
+  /** One attachment of an email with a signed download link. */
+  getAttachment(emailId, attachmentId) {
+    return this.client.request(
+      "GET",
+      `/v1/emails/${encodeURIComponent(emailId)}/attachments/${encodeURIComponent(attachmentId)}`
+    );
+  }
 };
 
 // src/batch.ts
@@ -84,11 +128,19 @@ var Batch = class {
     this.client = client;
   }
   client;
-  /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-  send(emails) {
-    return this.client.request("POST", "/v1/emails/batch", {
-      emails: emails.map(toWirePayload)
-    });
+  /**
+   * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+   * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+   * to retry.
+   */
+  send(emails, requestOptions) {
+    return this.client.request(
+      "POST",
+      "/v1/emails/batch",
+      { emails: emails.map(toWirePayload) },
+      void 0,
+      requestOptions
+    );
   }
   /** Batch progress: how many emails are in each status so far. */
   get(id) {
@@ -147,7 +199,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.3.0";
+var USER_AGENT = "retransmit.dev-node/0.5.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -172,7 +224,7 @@ var Retransmit = class {
     );
   }
   /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-  async request(method, path, body, query) {
+  async request(method, path, body, query, options = {}) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query ?? {})) {
       if (value === void 0) continue;
@@ -180,15 +232,19 @@ var Retransmit = class {
     }
     const encoded = params.toString();
     const search = encoded ? `?${encoded}` : "";
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT
+    };
+    if (options.idempotencyKey !== void 0) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
     let response;
     try {
       response = await fetch(`${this.baseUrl}${path}${search}`, {
         method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": USER_AGENT
-        },
+        headers,
         body: body === void 0 ? void 0 : JSON.stringify(body)
       });
     } catch (cause) {

package/dist/index.d.cts

@@ -20,6 +20,18 @@ interface RetransmitOptions {
     /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
     baseUrl?: string;
 }
+/** Per-request options, passed as the second argument of `emails.send` and `batch.send`. */
+interface RequestOptions {
+    /**
+     * Makes the request safe to retry. Sent as the `Idempotency-Key` header.
+     * For 24 hours, a retry with the same key and payload returns the original
+     * response instead of queuing the email again. 1 to 256 characters; a UUID
+     * or `<event>/<entity-id>` such as `welcome-user/123` works well. A retry
+     * with a different payload fails with `invalid_idempotent_request`, and one
+     * that overlaps the first request fails with `concurrent_idempotent_requests`.
+     */
+    idempotencyKey?: string;
+}
 interface SendEmailOptions {
     /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
     from: string;
@@ -47,6 +59,68 @@ interface SendEmailOptions {
      * and are never sent to the recipient.
      */
     tags?: EmailTag[];
+    /**
+     * Custom message headers, keyed by header name, for example
+     * `{ "X-Entity-Ref-ID": "order_4821" }` to stop Gmail threading related
+     * emails together. Up to 20 headers. Names are printable ASCII without `:`
+     * (up to 126 characters); values are single-line, up to 870 characters.
+     * Headers Retransmit sets itself (From, To, Cc, Bcc, Reply-To, Subject,
+     * Date, Message-ID, Return-Path, MIME/Content-* and DKIM-Signature) are
+     * rejected with a `validation_error`. On marketing emails the hosted
+     * List-Unsubscribe headers take precedence over yours.
+     */
+    headers?: EmailHeaders;
+    /**
+     * Files to attach, up to 20 per email and 30 MB in total. Each needs a
+     * `filename` and either `content` (the bytes) or `path` (a public URL
+     * fetched when you call `send`). Add `contentId` to embed an image inline.
+     * Not accepted by `batch.send`.
+     */
+    attachments?: Attachment[];
+}
+type EmailHeaders = Record<string, string>;
+/** A file to attach. Provide exactly one of `content` and `path`. */
+interface Attachment {
+    /**
+     * Name the recipient sees, up to 255 characters, no path separators. Its
+     * extension sets the content type when `contentType` is omitted.
+     */
+    filename: string;
+    /** The file: a `Buffer`, a `Uint8Array`, or an already base64 encoded string. */
+    content?: string | Uint8Array;
+    /**
+     * Public http(s) URL the file is fetched from while the request runs, with
+     * a 15 second budget. Private and internal hosts are refused.
+     */
+    path?: string;
+    /** MIME type such as `application/pdf`. Inferred from the filename when omitted. */
+    contentType?: string;
+    /**
+     * Embeds the file inline and sets its Content-ID. Reference it in `html`
+     * as `<img src="cid:the-id">`. Letters, digits, `.`, `_`, `@` and `-`, up
+     * to 128 characters, unique per email.
+     */
+    contentId?: string;
+}
+/** An attachment as it was sent, without a download link. */
+interface EmailAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Size in bytes of the decoded file. */
+    size: number;
+    content_id: string | null;
+    /** True for images embedded via `contentId`. */
+    inline: boolean;
+}
+interface EmailAttachmentWithDownload extends EmailAttachment {
+    /** When the stored file is deleted, 30 days after the send. */
+    expires_at: string;
+    /** Signed link to download the file, valid for one hour. `null` once the file has expired. */
+    download_url: string | null;
+}
+interface ListEmailAttachmentsResponse {
+    attachments: EmailAttachmentWithDownload[];
 }
 interface EmailTag {
     name: string;
@@ -72,11 +146,15 @@ interface GetEmailResponse {
     subject: string;
     marketing: boolean;
     tags: EmailTag[];
+    /** Custom headers given at send time, or null. */
+    headers: EmailHeaders | null;
     status: EmailStatus;
     error: string | null;
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
+    /** Attachments given at send time, without download links. See `emails.attachments`. */
+    attachments: EmailAttachment[];
 }
 interface ListEmailsOptions {
     /**
@@ -255,8 +333,12 @@ interface GetBatchResponse {
 declare class Batch {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-    send(emails: SendEmailOptions[]): Promise<Result<SendBatchResponse>>;
+    /**
+     * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+     * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+     * to retry.
+     */
+    send(emails: SendEmailOptions[], requestOptions?: RequestOptions): Promise<Result<SendBatchResponse>>;
     /** Batch progress: how many emails are in each status so far. */
     get(id: string): Promise<Result<GetBatchResponse>>;
 }
@@ -264,8 +346,11 @@ declare class Batch {
 declare class Emails {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-    send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
+    /**
+     * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+     * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+     */
+    send(options: SendEmailOptions, requestOptions?: RequestOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
     /**
@@ -275,6 +360,14 @@ declare class Emails {
     list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
     /** Every distinct tag on your emails, with a count of emails carrying it. */
     tags(): Promise<Result<ListEmailTagsResponse>>;
+    /**
+     * The attachments of an email, each with a signed `download_url` valid for
+     * one hour. Files are kept for 30 days after the send; after that the link
+     * is `null` and only the metadata remains.
+     */
+    attachments(emailId: string): Promise<Result<ListEmailAttachmentsResponse>>;
+    /** One attachment of an email with a signed download link. */
+    getAttachment(emailId: string, attachmentId: string): Promise<Result<EmailAttachmentWithDownload>>;
 }
 
 declare class Sms {
@@ -308,7 +401,7 @@ declare class Retransmit {
     private readonly baseUrl;
     constructor(apiKey?: string, options?: RetransmitOptions);
     /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };
+export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };

package/dist/index.d.ts

@@ -20,6 +20,18 @@ interface RetransmitOptions {
     /** Override the API origin. Defaults to `https://api.retransmit.dev` (or `RETRANSMIT_BASE_URL`). */
     baseUrl?: string;
 }
+/** Per-request options, passed as the second argument of `emails.send` and `batch.send`. */
+interface RequestOptions {
+    /**
+     * Makes the request safe to retry. Sent as the `Idempotency-Key` header.
+     * For 24 hours, a retry with the same key and payload returns the original
+     * response instead of queuing the email again. 1 to 256 characters; a UUID
+     * or `<event>/<entity-id>` such as `welcome-user/123` works well. A retry
+     * with a different payload fails with `invalid_idempotent_request`, and one
+     * that overlaps the first request fails with `concurrent_idempotent_requests`.
+     */
+    idempotencyKey?: string;
+}
 interface SendEmailOptions {
     /** Sender, as `address@domain.com` or `Name <address@domain.com>`. The domain must be verified on your account. */
     from: string;
@@ -47,6 +59,68 @@ interface SendEmailOptions {
      * and are never sent to the recipient.
      */
     tags?: EmailTag[];
+    /**
+     * Custom message headers, keyed by header name, for example
+     * `{ "X-Entity-Ref-ID": "order_4821" }` to stop Gmail threading related
+     * emails together. Up to 20 headers. Names are printable ASCII without `:`
+     * (up to 126 characters); values are single-line, up to 870 characters.
+     * Headers Retransmit sets itself (From, To, Cc, Bcc, Reply-To, Subject,
+     * Date, Message-ID, Return-Path, MIME/Content-* and DKIM-Signature) are
+     * rejected with a `validation_error`. On marketing emails the hosted
+     * List-Unsubscribe headers take precedence over yours.
+     */
+    headers?: EmailHeaders;
+    /**
+     * Files to attach, up to 20 per email and 30 MB in total. Each needs a
+     * `filename` and either `content` (the bytes) or `path` (a public URL
+     * fetched when you call `send`). Add `contentId` to embed an image inline.
+     * Not accepted by `batch.send`.
+     */
+    attachments?: Attachment[];
+}
+type EmailHeaders = Record<string, string>;
+/** A file to attach. Provide exactly one of `content` and `path`. */
+interface Attachment {
+    /**
+     * Name the recipient sees, up to 255 characters, no path separators. Its
+     * extension sets the content type when `contentType` is omitted.
+     */
+    filename: string;
+    /** The file: a `Buffer`, a `Uint8Array`, or an already base64 encoded string. */
+    content?: string | Uint8Array;
+    /**
+     * Public http(s) URL the file is fetched from while the request runs, with
+     * a 15 second budget. Private and internal hosts are refused.
+     */
+    path?: string;
+    /** MIME type such as `application/pdf`. Inferred from the filename when omitted. */
+    contentType?: string;
+    /**
+     * Embeds the file inline and sets its Content-ID. Reference it in `html`
+     * as `<img src="cid:the-id">`. Letters, digits, `.`, `_`, `@` and `-`, up
+     * to 128 characters, unique per email.
+     */
+    contentId?: string;
+}
+/** An attachment as it was sent, without a download link. */
+interface EmailAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Size in bytes of the decoded file. */
+    size: number;
+    content_id: string | null;
+    /** True for images embedded via `contentId`. */
+    inline: boolean;
+}
+interface EmailAttachmentWithDownload extends EmailAttachment {
+    /** When the stored file is deleted, 30 days after the send. */
+    expires_at: string;
+    /** Signed link to download the file, valid for one hour. `null` once the file has expired. */
+    download_url: string | null;
+}
+interface ListEmailAttachmentsResponse {
+    attachments: EmailAttachmentWithDownload[];
 }
 interface EmailTag {
     name: string;
@@ -72,11 +146,15 @@ interface GetEmailResponse {
     subject: string;
     marketing: boolean;
     tags: EmailTag[];
+    /** Custom headers given at send time, or null. */
+    headers: EmailHeaders | null;
     status: EmailStatus;
     error: string | null;
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
+    /** Attachments given at send time, without download links. See `emails.attachments`. */
+    attachments: EmailAttachment[];
 }
 interface ListEmailsOptions {
     /**
@@ -255,8 +333,12 @@ interface GetBatchResponse {
 declare class Batch {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues up to 10,000 emails in one request. Track progress with `get(id)`. */
-    send(emails: SendEmailOptions[]): Promise<Result<SendBatchResponse>>;
+    /**
+     * Queues up to 10,000 emails in one request. Track progress with `get(id)`.
+     * Pass `{ idempotencyKey }` covering the whole batch to make the call safe
+     * to retry.
+     */
+    send(emails: SendEmailOptions[], requestOptions?: RequestOptions): Promise<Result<SendBatchResponse>>;
     /** Batch progress: how many emails are in each status so far. */
     get(id: string): Promise<Result<GetBatchResponse>>;
 }
@@ -264,8 +346,11 @@ declare class Batch {
 declare class Emails {
     private readonly client;
     constructor(client: Retransmit);
-    /** Queues a single email. Poll `get(id)` or subscribe to webhooks for the outcome. */
-    send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
+    /**
+     * Queues a single email. Poll `get(id)` or subscribe to webhooks for the
+     * outcome. Pass `{ idempotencyKey }` to make the call safe to retry.
+     */
+    send(options: SendEmailOptions, requestOptions?: RequestOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
     /**
@@ -275,6 +360,14 @@ declare class Emails {
     list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
     /** Every distinct tag on your emails, with a count of emails carrying it. */
     tags(): Promise<Result<ListEmailTagsResponse>>;
+    /**
+     * The attachments of an email, each with a signed `download_url` valid for
+     * one hour. Files are kept for 30 days after the send; after that the link
+     * is `null` and only the metadata remains.
+     */
+    attachments(emailId: string): Promise<Result<ListEmailAttachmentsResponse>>;
+    /** One attachment of an email with a signed download link. */
+    getAttachment(emailId: string, attachmentId: string): Promise<Result<EmailAttachmentWithDownload>>;
 }
 
 declare class Sms {
@@ -308,7 +401,7 @@ declare class Retransmit {
     private readonly baseUrl;
     constructor(apiKey?: string, options?: RetransmitOptions);
     /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>, options?: RequestOptions): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };
+export { type Attachment, Batch, EMAIL_STATUSES, type EmailAttachment, type EmailAttachmentWithDownload, type EmailEvent, type EmailStatus, type EmailSummary, type EmailTag, type EmailTagCount, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, type ListEmailAttachmentsResponse, type ListEmailTagsResponse, type ListEmailsOptions, type ListEmailsResponse, type RequestOptions, type Result, Retransmit, type RetransmitError, type RetransmitOptions, SMS_STATUSES, type SendBatchResponse, type SendEmailOptions, type SendEmailResponse, type SendSmsOptions, type SendSmsResponse, type SendWhatsappOptions, type SendWhatsappResponse, Sms, type SmsEvent, type SmsStatus, WHATSAPP_STATUSES, Whatsapp, type WhatsappDocument, type WhatsappEvent, type WhatsappMedia, type WhatsappMessageType, type WhatsappStatus, type WhatsappTemplate };