@unsent/sdk 1.0.0 → 1.0.1

package/README.md

@@ -60,8 +60,8 @@ const { data, error } = await client.emails.send({
   to: "hello@acme.com",
   from: "hello@company.com",
   subject: "unsent email",
-  html: "<p>unsent is the best open source product to send emails</p>",
-  text: "unsent is the best open source product to send emails",
+  html: "<p>unsent is the best email service provider to send emails</p>",
+  text: "unsent is the best email service provider to send emails",
 });
 
 if (error) {
@@ -143,6 +143,60 @@ if (error) {
 }
 ```
 
+#### Idempotency Keys
+
+Safely retry email sends with an idempotency key to prevent duplicate sends. This is especially useful for critical emails like signup confirmations or password resets.
+
+```typescript
+// Safely retry sends with an idempotency key
+const { data, error } = await client.emails.send(
+  {
+    to: "hello@acme.com",
+    from: "hello@company.com",
+    subject: "unsent email",
+    html: "<p>unsent is the best open source product to send emails</p>",
+  },
+  { idempotencyKey: "signup-123" },
+);
+
+if (error) {
+  console.error("Error:", error);
+} else {
+  console.log("Email sent! ID:", data.id);
+}
+```
+
+Idempotency keys also work for batch sends:
+
+```typescript
+// Works for bulk sends too
+const { data, error } = await client.emails.batch(
+  [
+    {
+      to: "a@example.com",
+      from: "hello@company.com",
+      subject: "Welcome",
+      html: "<p>Hello A</p>",
+    },
+    {
+      to: "b@example.com",
+      from: "hello@company.com",
+      subject: "Welcome",
+      html: "<p>Hello B</p>",
+    },
+  ],
+  { idempotencyKey: "bulk-welcome-1" },
+);
+
+if (error) {
+  console.error("Error:", error);
+} else {
+  console.log(`Sent ${data.length} emails`);
+}
+```
+
+> **Note:** Reusing the same idempotency key with a different payload will return HTTP 409 (Conflict). This ensures that retries are safe and prevents accidental duplicate sends with modified content.
+
 ### Managing Emails
 
 #### Get Email Details

package/dist/index.d.mts

@@ -1312,6 +1312,12 @@ type BatchEmailPayload = paths["/v1/emails/batch"]["post"]["requestBody"]["conte
  * Successful response schema for batch email send.
  */
 type BatchEmailResponseSuccess = paths["/v1/emails/batch"]["post"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Options for email requests.
+ */
+type EmailRequestOptions = {
+    idempotencyKey?: string;
+};
 /**
  * Response structure for the batch method.
  */
@@ -1322,15 +1328,15 @@ type BatchEmailResponse = {
 declare class Emails {
     private readonly unsent;
     constructor(unsent: unsent);
-    send(payload: SendEmailPayload): Promise<CreateEmailResponse>;
-    create(payload: SendEmailPayload): Promise<CreateEmailResponse>;
+    send(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
+    create(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
     /**
      * Send up to 100 emails in a single request.
      *
      * @param payload An array of email payloads. Max 100 emails.
      * @returns A promise that resolves to the list of created email IDs or an error.
      */
-    batch(payload: BatchEmailPayload): Promise<BatchEmailResponse>;
+    batch(payload: BatchEmailPayload, options?: EmailRequestOptions): Promise<BatchEmailResponse>;
     get(id: string): Promise<GetEmailResponse>;
     update(id: string, payload: UpdateEmailPayload): Promise<UpdateEmailResponse>;
     cancel(id: string): Promise<CancelEmailResponse>;
@@ -1419,7 +1425,9 @@ declare class unsent {
         data: T | null;
         error: ErrorResponse | null;
     }>;
-    post<T>(path: string, body: unknown): Promise<{
+    post<T>(path: string, body: unknown, options?: {
+        headers?: Record<string, string>;
+    }): Promise<{
         data: T | null;
         error: ErrorResponse | null;
     }>;

package/dist/index.d.ts

@@ -1312,6 +1312,12 @@ type BatchEmailPayload = paths["/v1/emails/batch"]["post"]["requestBody"]["conte
  * Successful response schema for batch email send.
  */
 type BatchEmailResponseSuccess = paths["/v1/emails/batch"]["post"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Options for email requests.
+ */
+type EmailRequestOptions = {
+    idempotencyKey?: string;
+};
 /**
  * Response structure for the batch method.
  */
@@ -1322,15 +1328,15 @@ type BatchEmailResponse = {
 declare class Emails {
     private readonly unsent;
     constructor(unsent: unsent);
-    send(payload: SendEmailPayload): Promise<CreateEmailResponse>;
-    create(payload: SendEmailPayload): Promise<CreateEmailResponse>;
+    send(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
+    create(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
     /**
      * Send up to 100 emails in a single request.
      *
      * @param payload An array of email payloads. Max 100 emails.
      * @returns A promise that resolves to the list of created email IDs or an error.
      */
-    batch(payload: BatchEmailPayload): Promise<BatchEmailResponse>;
+    batch(payload: BatchEmailPayload, options?: EmailRequestOptions): Promise<BatchEmailResponse>;
     get(id: string): Promise<GetEmailResponse>;
     update(id: string, payload: UpdateEmailPayload): Promise<UpdateEmailResponse>;
     cancel(id: string): Promise<CancelEmailResponse>;
@@ -1419,7 +1425,9 @@ declare class unsent {
         data: T | null;
         error: ErrorResponse | null;
     }>;
-    post<T>(path: string, body: unknown): Promise<{
+    post<T>(path: string, body: unknown, options?: {
+        headers?: Record<string, string>;
+    }): Promise<{
         data: T | null;
         error: ErrorResponse | null;
     }>;

package/dist/index.js

@@ -73,17 +73,18 @@ var Emails = class {
     this.unsent = unsent2;
     this.unsent = unsent2;
   }
-  async send(payload) {
-    return this.create(payload);
+  async send(payload, options) {
+    return this.create(payload, options);
   }
-  async create(payload) {
+  async create(payload, options) {
     if (payload.react) {
       payload.html = await (0, import_render.render)(payload.react);
       delete payload.react;
     }
     const data = await this.unsent.post(
       "/emails",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return data;
   }
@@ -93,10 +94,11 @@ var Emails = class {
    * @param payload An array of email payloads. Max 100 emails.
    * @returns A promise that resolves to the list of created email IDs or an error.
    */
-  async batch(payload) {
+  async batch(payload, options) {
     const response = await this.unsent.post(
       "/emails/batch",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return {
       data: response.data ? response.data.data : null,
@@ -264,10 +266,16 @@ var unsent = class {
     const data = await response.json();
     return { data, error: null };
   }
-  async post(path, body) {
+  async post(path, body, options) {
+    const headers = new Headers(this.headers);
+    if (options?.headers) {
+      Object.entries(options.headers).forEach(([key, value]) => {
+        headers.set(key, value);
+      });
+    }
     const requestOptions = {
       method: "POST",
-      headers: this.headers,
+      headers,
       body: JSON.stringify(body)
     };
     return this.fetchRequest(path, requestOptions);

package/dist/index.mjs

@@ -46,17 +46,18 @@ var Emails = class {
     this.unsent = unsent2;
     this.unsent = unsent2;
   }
-  async send(payload) {
-    return this.create(payload);
+  async send(payload, options) {
+    return this.create(payload, options);
   }
-  async create(payload) {
+  async create(payload, options) {
     if (payload.react) {
       payload.html = await render(payload.react);
       delete payload.react;
     }
     const data = await this.unsent.post(
       "/emails",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return data;
   }
@@ -66,10 +67,11 @@ var Emails = class {
    * @param payload An array of email payloads. Max 100 emails.
    * @returns A promise that resolves to the list of created email IDs or an error.
    */
-  async batch(payload) {
+  async batch(payload, options) {
     const response = await this.unsent.post(
       "/emails/batch",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return {
       data: response.data ? response.data.data : null,
@@ -237,10 +239,16 @@ var unsent = class {
     const data = await response.json();
     return { data, error: null };
   }
-  async post(path, body) {
+  async post(path, body, options) {
+    const headers = new Headers(this.headers);
+    if (options?.headers) {
+      Object.entries(options.headers).forEach(([key, value]) => {
+        headers.set(key, value);
+      });
+    }
     const requestOptions = {
       method: "POST",
-      headers: this.headers,
+      headers,
       body: JSON.stringify(body)
     };
     return this.fetchRequest(path, requestOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unsent/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "TypeScript SDK for the Unsent API - Send transactional emails with ease",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",