retransmit.dev 0.2.0 → 0.3.0

package/README.md

@@ -51,6 +51,57 @@ const { data } = await retransmit.emails.get("em_xxxxxxxxxxxx");
 console.log(data?.status); // "delivered"
 ```
 
+### Tags
+
+Attach up to 10 `{ name, value }` tags to an email to label it. Filter by
+them in the dashboard or with `emails.list`. Tags come back on `emails.get`
+and are never sent to the recipient.
+
+```ts
+await retransmit.emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: "user@example.com",
+  subject: "Your receipt",
+  html: "<p>Thanks for your order!</p>",
+  tags: [
+    { name: "category", value: "receipt" },
+    { name: "campaign", value: "spring-2026" },
+  ],
+});
+```
+
+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.
+
+### List and filter emails
+
+`emails.list` returns your emails newest first. Every tag you pass must match.
+Combine with `status` or `batchId`, and page with `cursor`:
+
+```ts
+const { data } = await retransmit.emails.list({
+  tags: [{ name: "campaign", value: "spring-2026" }],
+  status: "bounced",
+  limit: 100,
+});
+
+for (const email of data!.emails) {
+  console.log(email.id, email.to, email.status, email.tags);
+}
+
+if (data!.has_more) {
+  await retransmit.emails.list({ cursor: data!.next_cursor!, /* same filters */ });
+}
+```
+
+To see which tags exist on your account, and how many emails carry each:
+
+```ts
+const { data } = await retransmit.emails.tags();
+// data.tags: [{ name: "campaign", value: "spring-2026", count: 1240 }, ...]
+```
+
 ## SMS
 
 Use international E.164 phone numbers. A single request can contain up to 50

package/dist/index.cjs

@@ -42,7 +42,8 @@ function toWirePayload(options) {
     subject: options.subject,
     html: options.html,
     text: options.text,
-    marketing: options.marketing
+    marketing: options.marketing,
+    tags: options.tags
   };
 }
 var Emails = class {
@@ -58,6 +59,23 @@ var Emails = class {
   get(id) {
     return this.client.request("GET", `/v1/emails/${encodeURIComponent(id)}`);
   }
+  /**
+   * Lists your emails, newest first, optionally filtered by tags, status or
+   * batch. Pass `next_cursor` back as `cursor` to page through the results.
+   */
+  list(options = {}) {
+    return this.client.request("GET", "/v1/emails", void 0, {
+      tag: options.tags?.map((tag) => `${tag.name}:${tag.value}`),
+      status: options.status,
+      batch_id: options.batchId,
+      limit: options.limit,
+      cursor: options.cursor
+    });
+  }
+  /** Every distinct tag on your emails, with a count of emails carrying it. */
+  tags() {
+    return this.client.request("GET", "/v1/emails/tags");
+  }
 };
 
 // src/batch.ts
@@ -129,7 +147,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.1.0";
+var USER_AGENT = "retransmit.dev-node/0.3.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -154,10 +172,17 @@ var Retransmit = class {
     );
   }
   /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-  async request(method, path, body) {
+  async request(method, path, body, query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value === void 0) continue;
+      for (const item of Array.isArray(value) ? value : [value]) params.append(key, String(item));
+    }
+    const encoded = params.toString();
+    const search = encoded ? `?${encoded}` : "";
     let response;
     try {
-      response = await fetch(`${this.baseUrl}${path}`, {
+      response = await fetch(`${this.baseUrl}${path}${search}`, {
         method,
         headers: {
           Authorization: `Bearer ${this.apiKey}`,

package/dist/index.d.cts

@@ -39,6 +39,18 @@ interface SendEmailOptions {
      * headers, and skips recipients who already unsubscribed.
      */
     marketing?: boolean;
+    /**
+     * Up to 10 labels for filtering emails in the dashboard, for example
+     * `[{ name: "campaign", value: "outreach-1" }]`. Names and values allow
+     * letters, digits, underscores and dashes, up to 256 characters each.
+     * Names must be unique within one email. Tags are returned by `emails.get`
+     * and are never sent to the recipient.
+     */
+    tags?: EmailTag[];
+}
+interface EmailTag {
+    name: string;
+    value: string;
 }
 interface SendEmailResponse {
     id: string;
@@ -59,12 +71,55 @@ interface GetEmailResponse {
     reply_to: string[] | null;
     subject: string;
     marketing: boolean;
+    tags: EmailTag[];
     status: EmailStatus;
     error: string | null;
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
 }
+interface ListEmailsOptions {
+    /**
+     * Only emails carrying every one of these tags, for example
+     * `[{ name: "campaign", value: "outreach-1" }]`.
+     */
+    tags?: EmailTag[];
+    status?: EmailStatus;
+    /** Only emails sent as part of this batch. */
+    batchId?: string;
+    /** Page size, 1 to 100. Defaults to 50. */
+    limit?: number;
+    /** `next_cursor` from the previous page. */
+    cursor?: string;
+}
+/** One row of `emails.list`. Call `emails.get(id)` for the event history. */
+interface EmailSummary {
+    id: string;
+    batch_id: string | null;
+    from: string;
+    to: string[];
+    subject: string;
+    marketing: boolean;
+    tags: EmailTag[];
+    status: EmailStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+}
+interface ListEmailsResponse {
+    /** Newest first. */
+    emails: EmailSummary[];
+    has_more: boolean;
+    /** Pass back as `cursor` to fetch the next page. `null` on the last page. */
+    next_cursor: string | null;
+}
+interface EmailTagCount extends EmailTag {
+    /** How many of your emails carry this tag. */
+    count: number;
+}
+interface ListEmailTagsResponse {
+    tags: EmailTagCount[];
+}
 declare const SMS_STATUSES: readonly ["queued", "sent", "delivered", "undelivered", "expired", "rejected", "failed"];
 type SmsStatus = (typeof SMS_STATUSES)[number];
 interface SendSmsOptions {
@@ -213,6 +268,13 @@ declare class Emails {
     send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
+    /**
+     * Lists your emails, newest first, optionally filtered by tags, status or
+     * batch. Pass `next_cursor` back as `cursor` to page through the results.
+     */
+    list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
+    /** Every distinct tag on your emails, with a count of emails carrying it. */
+    tags(): Promise<Result<ListEmailTagsResponse>>;
 }
 
 declare class Sms {
@@ -246,7 +308,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): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, 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 { 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 };

package/dist/index.d.ts

@@ -39,6 +39,18 @@ interface SendEmailOptions {
      * headers, and skips recipients who already unsubscribed.
      */
     marketing?: boolean;
+    /**
+     * Up to 10 labels for filtering emails in the dashboard, for example
+     * `[{ name: "campaign", value: "outreach-1" }]`. Names and values allow
+     * letters, digits, underscores and dashes, up to 256 characters each.
+     * Names must be unique within one email. Tags are returned by `emails.get`
+     * and are never sent to the recipient.
+     */
+    tags?: EmailTag[];
+}
+interface EmailTag {
+    name: string;
+    value: string;
 }
 interface SendEmailResponse {
     id: string;
@@ -59,12 +71,55 @@ interface GetEmailResponse {
     reply_to: string[] | null;
     subject: string;
     marketing: boolean;
+    tags: EmailTag[];
     status: EmailStatus;
     error: string | null;
     created_at: string;
     last_event_at: string | null;
     events: EmailEvent[];
 }
+interface ListEmailsOptions {
+    /**
+     * Only emails carrying every one of these tags, for example
+     * `[{ name: "campaign", value: "outreach-1" }]`.
+     */
+    tags?: EmailTag[];
+    status?: EmailStatus;
+    /** Only emails sent as part of this batch. */
+    batchId?: string;
+    /** Page size, 1 to 100. Defaults to 50. */
+    limit?: number;
+    /** `next_cursor` from the previous page. */
+    cursor?: string;
+}
+/** One row of `emails.list`. Call `emails.get(id)` for the event history. */
+interface EmailSummary {
+    id: string;
+    batch_id: string | null;
+    from: string;
+    to: string[];
+    subject: string;
+    marketing: boolean;
+    tags: EmailTag[];
+    status: EmailStatus;
+    error: string | null;
+    created_at: string;
+    last_event_at: string | null;
+}
+interface ListEmailsResponse {
+    /** Newest first. */
+    emails: EmailSummary[];
+    has_more: boolean;
+    /** Pass back as `cursor` to fetch the next page. `null` on the last page. */
+    next_cursor: string | null;
+}
+interface EmailTagCount extends EmailTag {
+    /** How many of your emails carry this tag. */
+    count: number;
+}
+interface ListEmailTagsResponse {
+    tags: EmailTagCount[];
+}
 declare const SMS_STATUSES: readonly ["queued", "sent", "delivered", "undelivered", "expired", "rejected", "failed"];
 type SmsStatus = (typeof SMS_STATUSES)[number];
 interface SendSmsOptions {
@@ -213,6 +268,13 @@ declare class Emails {
     send(options: SendEmailOptions): Promise<Result<SendEmailResponse>>;
     /** Retrieves an email with its current status and event history. */
     get(id: string): Promise<Result<GetEmailResponse>>;
+    /**
+     * Lists your emails, newest first, optionally filtered by tags, status or
+     * batch. Pass `next_cursor` back as `cursor` to page through the results.
+     */
+    list(options?: ListEmailsOptions): Promise<Result<ListEmailsResponse>>;
+    /** Every distinct tag on your emails, with a count of emails carrying it. */
+    tags(): Promise<Result<ListEmailTagsResponse>>;
 }
 
 declare class Sms {
@@ -246,7 +308,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): Promise<Result<T>>;
+    request<T>(method: "GET" | "POST", path: string, body?: unknown, query?: Record<string, string | number | string[] | undefined>): Promise<Result<T>>;
 }
 
-export { Batch, EMAIL_STATUSES, type EmailEvent, type EmailStatus, Emails, type GetBatchResponse, type GetEmailResponse, type GetSmsResponse, type GetWhatsappResponse, 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 { 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 };

package/dist/index.js

@@ -9,7 +9,8 @@ function toWirePayload(options) {
     subject: options.subject,
     html: options.html,
     text: options.text,
-    marketing: options.marketing
+    marketing: options.marketing,
+    tags: options.tags
   };
 }
 var Emails = class {
@@ -25,6 +26,23 @@ var Emails = class {
   get(id) {
     return this.client.request("GET", `/v1/emails/${encodeURIComponent(id)}`);
   }
+  /**
+   * Lists your emails, newest first, optionally filtered by tags, status or
+   * batch. Pass `next_cursor` back as `cursor` to page through the results.
+   */
+  list(options = {}) {
+    return this.client.request("GET", "/v1/emails", void 0, {
+      tag: options.tags?.map((tag) => `${tag.name}:${tag.value}`),
+      status: options.status,
+      batch_id: options.batchId,
+      limit: options.limit,
+      cursor: options.cursor
+    });
+  }
+  /** Every distinct tag on your emails, with a count of emails carrying it. */
+  tags() {
+    return this.client.request("GET", "/v1/emails/tags");
+  }
 };
 
 // src/batch.ts
@@ -96,7 +114,7 @@ var Whatsapp = class {
 
 // src/retransmit.ts
 var DEFAULT_BASE_URL = "https://api.retransmit.dev";
-var USER_AGENT = "retransmit.dev-node/0.1.0";
+var USER_AGENT = "retransmit.dev-node/0.3.0";
 function readEnv(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -121,10 +139,17 @@ var Retransmit = class {
     );
   }
   /** Internal transport shared by the resource classes. API failures are returned, never thrown. */
-  async request(method, path, body) {
+  async request(method, path, body, query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value === void 0) continue;
+      for (const item of Array.isArray(value) ? value : [value]) params.append(key, String(item));
+    }
+    const encoded = params.toString();
+    const search = encoded ? `?${encoded}` : "";
     let response;
     try {
-      response = await fetch(`${this.baseUrl}${path}`, {
+      response = await fetch(`${this.baseUrl}${path}${search}`, {
         method,
         headers: {
           Authorization: `Bearer ${this.apiKey}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retransmit.dev",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Node.js SDK for the Retransmit email, SMS and WhatsApp APIs",
   "keywords": [
     "email",