@nxgt/mail-resend 0.2.0 → 0.3.0

package/README.md

@@ -33,8 +33,8 @@ bun add @nxgt/mail-resend @nxgt/mail
 
 Peers, all required:
 
-- `@nxgt/mail` — the port, the errors and the checks: `^0.2`, the version
-  with attachments. One copy in your tree, so `error instanceof MailFailure`
+- `@nxgt/mail` — the port, the errors and the checks: `^0.3`, the version
+  with attachments and `idempotencyKey`. One copy in your tree, so `error instanceof MailFailure`
   holds.
 - `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
   what is supported and tested; `nodenext` is out of contract.
@@ -109,12 +109,43 @@ base64** — a third larger than the files — and refuses more (`MailRefused`).
 **A large or sensitive file is a signed link in the template**, not an
 attachment. See [Setting up — what a message becomes](docs/guide/setup.md#what-a-message-becomes).
 
+### Idempotency — a retry that delivers once
+
+A message's `idempotencyKey` is sent as Resend's `Idempotency-Key` header.
+Resend keeps a key for **24 hours**: a retry within them answers the first
+send's id, and delivers nothing more.
+
+```ts
+import { MailFailure } from '@nxgt/mail';
+
+const receipt = {
+	to: 'ada@example.com',
+	subject: 'Your receipt',
+	html: '<p>Thank you for your order.</p>',
+	text: 'Thank you for your order.',
+	idempotencyKey: 'order-42/receipt', // from what the e-mail is about, never the time or a random value
+};
+
+const sent = await mailer.send(receipt).catch(async (error: unknown) => {
+	if (!(error instanceof MailFailure)) throw error;
+	return mailer.send(receipt); // a timeout may have delivered it: the key keeps it to one e-mail
+});
+```
+
+The same key with a **different** message is refused by Resend
+(`409 invalid_idempotent_request`, a `MailRefused`): a key names one e-mail.
+The same key while its first send is **still in progress**
+(`409 concurrent_idempotent_requests`) is a `MailFailure`: retry later. Past
+24 hours, the key is forgotten and a retry delivers again. The key never
+reaches the e-mail. See
+[Setting up — the idempotency key](docs/guide/setup.md#the-idempotency-key).
+
 ### Errors — a refusal or a failure
 
 | When | Throws | `cause` |
 | --- | --- | --- |
-| `400`, `422` — Resend refuses the message, an attachment over the size limit included; `413` — a request too large for what sits in front of the API | `MailRefused` — `send: Resend refused the message` | an `Error` with `status`, `errorName` and Resend's `detail` |
-| `401`, `403`, `429`, `5xx`, any other status | `MailFailure` — `send: Resend could not take the message` | the same |
+| `400`, `422` — Resend refuses the message, an attachment over the size limit included; `413` — a request too large for what sits in front of the API; `409 invalid_idempotent_request` — the `idempotencyKey` already used for a different message | `MailRefused` — `send: Resend refused the message` | an `Error` with `status`, `errorName` and Resend's `detail` |
+| `401`, `403`, `429`, `5xx`, `409 concurrent_idempotent_requests` — the same key's first send still in progress — any other status | `MailFailure` — `send: Resend could not take the message` | the same |
 | A network error | `MailFailure` — `send: Resend could not be reached` | the `fetch` error |
 | No answer within `timeoutMs` | `MailFailure` — `send: Resend did not answer within <timeoutMs> ms` | the `TimeoutError` |
 | No sender, on the message or as a default | `MailRefused` — `send: from is missing — give the message a from, or createResendMailer a default one` | — |
@@ -168,7 +199,8 @@ The transport does not wait and retry for you.
 
 **A timeout does not mean nothing was sent.** After `timeoutMs`, or a
 connection dropped mid-request, Resend may have accepted the e-mail: a retry
-can send it twice. Weigh that before retrying.
+without a key can send it twice. Set `idempotencyKey: 'order-42/receipt'`,
+and retry within Resend's 24 hours.
 
 ## Type safety, counted
 

package/dist/index.d.ts

@@ -12,7 +12,9 @@
  * ```
  *
  * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`
- * peer, what Resend answered as the `cause`. Nothing is retried.
+ * peer, what Resend answered as the `cause`. Nothing is retried; a message's
+ * `idempotencyKey` is sent as Resend's `Idempotency-Key`, so a retry the
+ * caller makes delivers once.
  */
 import { type Address, type Mailer } from '@nxgt/mail';
 export interface ResendMailerOptions {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AAyID,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CA+FvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AA4KD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CA6EvE"}

package/dist/index.js

@@ -39,6 +39,27 @@ function base64Of(bytes) {
   }
   return btoa(binary);
 }
+function bodyOf(message, sender) {
+  const to = Array.isArray(message.to) ? message.to : [message.to];
+  return {
+    from: formatAddress(sender),
+    to: to.map(formatAddress),
+    subject: message.subject,
+    html: message.html,
+    text: message.text,
+    ...message.replyTo === undefined ? {} : {
+      reply_to: formatAddress(message.replyTo)
+    },
+    ...message.headers === undefined || Object.keys(message.headers).length === 0 ? {} : { headers: message.headers },
+    ...message.attachments === undefined || message.attachments.length === 0 ? {} : {
+      attachments: message.attachments.map((attachment) => ({
+        filename: attachment.filename,
+        content: base64Of(attachment.content),
+        content_type: attachment.contentType
+      }))
+    }
+  };
+}
 var MAX_TIMEOUT_MS = 2147483647;
 var text = (value) => typeof value === "string" && value !== "" ? value : null;
 function checkOptions(options) {
@@ -83,25 +104,7 @@ function createResendMailer(options) {
       if (sender === undefined) {
         throw new MailRefused("send: from is missing — give the message a from, or createResendMailer a default one");
       }
-      const to = Array.isArray(message.to) ? message.to : [message.to];
-      const body = {
-        from: formatAddress(sender),
-        to: to.map(formatAddress),
-        subject: message.subject,
-        html: message.html,
-        text: message.text,
-        ...message.replyTo === undefined ? {} : {
-          reply_to: formatAddress(message.replyTo)
-        },
-        ...message.headers === undefined ? {} : { headers: message.headers },
-        ...message.attachments === undefined || message.attachments.length === 0 ? {} : {
-          attachments: message.attachments.map((attachment) => ({
-            filename: attachment.filename,
-            content: base64Of(attachment.content),
-            content_type: attachment.contentType
-          }))
-        }
-      };
+      const body = bodyOf(message, sender);
       const signal = AbortSignal.timeout(timeoutMs);
       let response;
       try {
@@ -109,7 +112,8 @@ function createResendMailer(options) {
           method: "POST",
           headers: {
             authorization: `Bearer ${options.apiKey}`,
-            "content-type": "application/json"
+            "content-type": "application/json",
+            ...message.idempotencyKey === undefined ? {} : { "idempotency-key": message.idempotencyKey }
           },
           body: JSON.stringify(body),
           signal
@@ -126,7 +130,7 @@ function createResendMailer(options) {
       if (response.ok)
         return { messageId: text(answer.id) };
       const cause = resendAnswer(response.status, text(answer.name), text(answer.message));
-      if (response.status === 400 || response.status === 413 || response.status === 422) {
+      if (response.status === 400 || response.status === 413 || response.status === 422 || response.status === 409 && cause.errorName === "invalid_idempotent_request") {
         throw new MailRefused("send: Resend refused the message", { cause });
       }
       throw new MailFailure("send: Resend could not take the message", {
@@ -140,5 +144,5 @@ export {
   formatAddress
 };
 
-//# debugId=DBE3D2F49402DA0764756E2164756E21
+//# debugId=BC85082B780FD90964756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/index.ts"],
   "sourcesContent": [
-    "/**\n * `@nxgt/mail-resend` — a Resend transport for `@nxgt/mail`, over `fetch`,\n * with no SDK.\n *\n * ```ts\n * import { createResendMailer } from '@nxgt/mail-resend';\n *\n * const mailer = createResendMailer({\n *   apiKey: process.env.RESEND_API_KEY ?? '',\n *   from: { name: 'Acme', address: 'noreply@acme.test' },\n * });\n * ```\n *\n * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`\n * peer, what Resend answered as the `cause`. Nothing is retried.\n */\n\nimport {\n\ttype Address,\n\tcheckMessage,\n\ttype Mailer,\n\tMailFailure,\n\ttype MailMessage,\n\tMailRefused,\n\ttype SentMail,\n} from '@nxgt/mail';\n\nexport interface ResendMailerOptions {\n\t/** The API key, `re_…`. */\n\treadonly apiKey: string;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n\t/** Default `https://api.resend.com`. */\n\treadonly baseUrl?: string;\n\t/** Default the global `fetch`. For a proxy, or a test. */\n\treadonly fetch?: (url: string, init: RequestInit) => Promise<Response>;\n\t/** How long a send may take before it fails. Default `30000`. */\n\treadonly timeoutMs?: number;\n}\n\n/**\n * An address as Resend reads it: bare, or `\"name\" <address>` — the name a\n * quoted string, so a comma or an angle bracket in it names no one else.\n */\nexport function formatAddress(address: Address): string {\n\tif (typeof address === 'string') return address;\n\tconst name = address.name.replace(/[\\\\\"]/g, (char) => `\\\\${char}`);\n\treturn `\"${name}\" <${address.address}>`;\n}\n\n/**\n * What Resend answered, kept as the `cause`: a plain `Error` — a transport\n * defines no error class of its own — with the status, Resend's error name\n * (`validation_error`, `rate_limit_exceeded`…) and its message as `detail`.\n * Its own message holds the status and the name only: Resend's message can\n * quote an address, and a message reports a shape, never a value.\n */\nfunction resendAnswer(\n\tstatus: number,\n\terrorName: string | null,\n\tdetail: string | null,\n): Error & {\n\treadonly status: number;\n\treadonly errorName: string | null;\n\treadonly detail: string | null;\n} {\n\treturn Object.assign(\n\t\tnew Error(\n\t\t\t`Resend answered ${status}${errorName === null ? '' : ` ${errorName}`}`,\n\t\t),\n\t\t{ status, errorName, detail },\n\t);\n}\n\n/**\n * Settles with `work`, or rejects with the signal's reason once it aborts —\n * so the timeout holds even with an injected `fetch` that ignores the signal.\n */\nfunction beforeAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst abort = () => reject(signal.reason);\n\t\tif (signal.aborted) return abort();\n\t\tsignal.addEventListener('abort', abort, { once: true });\n\t\twork.then(\n\t\t\t(value) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\n/** The JSON body of an answer, or `{}` when it is not JSON or never ends. */\nasync function readAnswer(\n\tresponse: Response,\n\tsignal: AbortSignal,\n): Promise<Record<string, unknown>> {\n\tconst body: unknown = await beforeAbort(response.json(), signal).then(\n\t\t(value: unknown) => value,\n\t\t() => null,\n\t);\n\treturn typeof body === 'object' && body !== null\n\t\t? (body as Record<string, unknown>)\n\t\t: {};\n}\n\n/**\n * `bytes` as base64, as Resend takes an attachment's `content` — with no Node\n * built-in, so it runs on an edge runtime. Read in slices, so a large file\n * never spreads more arguments than a call takes.\n */\nfunction base64Of(bytes: Uint8Array): string {\n\tlet binary = '';\n\tfor (let start = 0; start < bytes.length; start += 0x8000) {\n\t\tbinary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));\n\t}\n\treturn btoa(binary);\n}\n\n/** The largest delay a timer takes, 2³¹ − 1 ms — about 24.8 days. */\nconst MAX_TIMEOUT_MS = 2_147_483_647;\n\nconst text = (value: unknown) =>\n\ttypeof value === 'string' && value !== '' ? value : null;\n\nfunction checkOptions(options: ResendMailerOptions): void {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: options must be an object, as { apiKey }',\n\t\t);\n\t}\n\tif (typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey must be a Resend API key — is the environment variable set?',\n\t\t);\n\t}\n\tif (/\\s/.test(options.apiKey)) {\n\t\t// A key read from a file often keeps its final line break; `fetch`\n\t\t// would then refuse the header at every send, as an outage.\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey holds whitespace — trim the value it was read from',\n\t\t);\n\t}\n\tif (\n\t\toptions.baseUrl !== undefined &&\n\t\t(typeof options.baseUrl !== 'string' ||\n\t\t\t!/^https?:\\/\\/[^/]/.test(options.baseUrl))\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: baseUrl must be an http: or https: URL',\n\t\t);\n\t}\n\tif (options.fetch !== undefined && typeof options.fetch !== 'function') {\n\t\tthrow new TypeError('createResendMailer: fetch must be a function');\n\t}\n\tif (\n\t\toptions.timeoutMs !== undefined &&\n\t\t!(Number.isInteger(options.timeoutMs) && options.timeoutMs > 0)\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: timeoutMs must be a positive integer',\n\t\t);\n\t}\n\tif (options.timeoutMs !== undefined && options.timeoutMs > MAX_TIMEOUT_MS) {\n\t\t// A timer's delay is a signed 32-bit integer: above it, the runtime\n\t\t// fires at once, and every send would time out.\n\t\tthrow new TypeError(\n\t\t\t`createResendMailer: timeoutMs must be at most ${MAX_TIMEOUT_MS} — a longer timer fires at once`,\n\t\t);\n\t}\n\tif (options.from !== undefined) {\n\t\ttry {\n\t\t\tcheckMessage({ to: options.from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }',\n\t\t\t);\n\t\t}\n\t}\n}\n\n/** Creates a {@link Mailer} that sends each message through Resend's API. */\nexport function createResendMailer(options: ResendMailerOptions): Mailer {\n\tcheckOptions(options);\n\tconst endpoint = `${(options.baseUrl ?? 'https://api.resend.com').replace(/\\/+$/, '')}/emails`;\n\tconst post =\n\t\toptions.fetch ??\n\t\t((url: string, init: RequestInit) => globalThis.fetch(url, init));\n\tconst timeoutMs = options.timeoutMs ?? 30_000;\n\n\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? options.from;\n\t\t\tif (sender === undefined) {\n\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t'send: from is missing — give the message a from, or createResendMailer a default one',\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\t\t\tconst body = {\n\t\t\t\tfrom: formatAddress(sender),\n\t\t\t\tto: to.map(formatAddress),\n\t\t\t\tsubject: message.subject,\n\t\t\t\thtml: message.html,\n\t\t\t\ttext: message.text,\n\t\t\t\t...(message.replyTo === undefined\n\t\t\t\t\t? {}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: Resend's wire format names the field, not us.\n\t\t\t\t\t\t\treply_to: formatAddress(message.replyTo),\n\t\t\t\t\t\t}),\n\t\t\t\t...(message.headers === undefined ? {} : { headers: message.headers }),\n\t\t\t\t...(message.attachments === undefined ||\n\t\t\t\tmessage.attachments.length === 0\n\t\t\t\t\t? {}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\tattachments: message.attachments.map((attachment) => ({\n\t\t\t\t\t\t\t\tfilename: attachment.filename,\n\t\t\t\t\t\t\t\tcontent: base64Of(attachment.content),\n\t\t\t\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: Resend's wire format names the field, not us.\n\t\t\t\t\t\t\t\tcontent_type: attachment.contentType,\n\t\t\t\t\t\t\t})),\n\t\t\t\t\t\t}),\n\t\t\t};\n\n\t\t\tconst signal = AbortSignal.timeout(timeoutMs);\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await beforeAbort(\n\t\t\t\t\tpost(endpoint, {\n\t\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\t\theaders: {\n\t\t\t\t\t\t\tauthorization: `Bearer ${options.apiKey}`,\n\t\t\t\t\t\t\t'content-type': 'application/json',\n\t\t\t\t\t\t},\n\t\t\t\t\t\tbody: JSON.stringify(body),\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t}),\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof DOMException && error.name === 'TimeoutError') {\n\t\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t\t`send: Resend did not answer within ${timeoutMs} ms`,\n\t\t\t\t\t\t{ cause: error },\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure('send: Resend could not be reached', {\n\t\t\t\t\tcause: error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst answer = await readAnswer(response, signal);\n\t\t\tif (response.ok) return { messageId: text(answer.id) };\n\n\t\t\tconst cause = resendAnswer(\n\t\t\t\tresponse.status,\n\t\t\t\ttext(answer.name),\n\t\t\t\ttext(answer.message),\n\t\t\t);\n\t\t\t// 400 and 422 are Resend refusing the message, and 413 a request too\n\t\t\t// large to take — attachments over the limit, which sending again\n\t\t\t// cannot fix. Anything else — a key refused, a rate limit, an outage —\n\t\t\t// is Resend failing to take it.\n\t\t\tif (\n\t\t\t\tresponse.status === 400 ||\n\t\t\t\tresponse.status === 413 ||\n\t\t\t\tresponse.status === 422\n\t\t\t) {\n\t\t\t\tthrow new MailRefused('send: Resend refused the message', { cause });\n\t\t\t}\n\t\t\tthrow new MailFailure('send: Resend could not take the message', {\n\t\t\t\tcause,\n\t\t\t});\n\t\t},\n\t};\n}\n"
+    "/**\n * `@nxgt/mail-resend` — a Resend transport for `@nxgt/mail`, over `fetch`,\n * with no SDK.\n *\n * ```ts\n * import { createResendMailer } from '@nxgt/mail-resend';\n *\n * const mailer = createResendMailer({\n *   apiKey: process.env.RESEND_API_KEY ?? '',\n *   from: { name: 'Acme', address: 'noreply@acme.test' },\n * });\n * ```\n *\n * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`\n * peer, what Resend answered as the `cause`. Nothing is retried; a message's\n * `idempotencyKey` is sent as Resend's `Idempotency-Key`, so a retry the\n * caller makes delivers once.\n */\n\nimport {\n\ttype Address,\n\tcheckMessage,\n\ttype Mailer,\n\tMailFailure,\n\ttype MailMessage,\n\tMailRefused,\n\ttype SentMail,\n} from '@nxgt/mail';\n\nexport interface ResendMailerOptions {\n\t/** The API key, `re_…`. */\n\treadonly apiKey: string;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n\t/** Default `https://api.resend.com`. */\n\treadonly baseUrl?: string;\n\t/** Default the global `fetch`. For a proxy, or a test. */\n\treadonly fetch?: (url: string, init: RequestInit) => Promise<Response>;\n\t/** How long a send may take before it fails. Default `30000`. */\n\treadonly timeoutMs?: number;\n}\n\n/**\n * An address as Resend reads it: bare, or `\"name\" <address>` — the name a\n * quoted string, so a comma or an angle bracket in it names no one else.\n */\nexport function formatAddress(address: Address): string {\n\tif (typeof address === 'string') return address;\n\tconst name = address.name.replace(/[\\\\\"]/g, (char) => `\\\\${char}`);\n\treturn `\"${name}\" <${address.address}>`;\n}\n\n/**\n * What Resend answered, kept as the `cause`: a plain `Error` — a transport\n * defines no error class of its own — with the status, Resend's error name\n * (`validation_error`, `rate_limit_exceeded`…) and its message as `detail`.\n * Its own message holds the status and the name only: Resend's message can\n * quote an address, and a message reports a shape, never a value.\n */\nfunction resendAnswer(\n\tstatus: number,\n\terrorName: string | null,\n\tdetail: string | null,\n): Error & {\n\treadonly status: number;\n\treadonly errorName: string | null;\n\treadonly detail: string | null;\n} {\n\treturn Object.assign(\n\t\tnew Error(\n\t\t\t`Resend answered ${status}${errorName === null ? '' : ` ${errorName}`}`,\n\t\t),\n\t\t{ status, errorName, detail },\n\t);\n}\n\n/**\n * Settles with `work`, or rejects with the signal's reason once it aborts —\n * so the timeout holds even with an injected `fetch` that ignores the signal.\n */\nfunction beforeAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst abort = () => reject(signal.reason);\n\t\tif (signal.aborted) return abort();\n\t\tsignal.addEventListener('abort', abort, { once: true });\n\t\twork.then(\n\t\t\t(value) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\n/** The JSON body of an answer, or `{}` when it is not JSON or never ends. */\nasync function readAnswer(\n\tresponse: Response,\n\tsignal: AbortSignal,\n): Promise<Record<string, unknown>> {\n\tconst body: unknown = await beforeAbort(response.json(), signal).then(\n\t\t(value: unknown) => value,\n\t\t() => null,\n\t);\n\treturn typeof body === 'object' && body !== null\n\t\t? (body as Record<string, unknown>)\n\t\t: {};\n}\n\n/**\n * `bytes` as base64, as Resend takes an attachment's `content` — with no Node\n * built-in, so it runs on an edge runtime. Read in slices, so a large file\n * never spreads more arguments than a call takes.\n */\nfunction base64Of(bytes: Uint8Array): string {\n\tlet binary = '';\n\tfor (let start = 0; start < bytes.length; start += 0x8000) {\n\t\tbinary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));\n\t}\n\treturn btoa(binary);\n}\n\n/** The JSON body of `POST /emails`: `message` in Resend's field names. */\nfunction bodyOf(\n\tmessage: MailMessage,\n\tsender: Address,\n): Record<string, unknown> {\n\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\treturn {\n\t\tfrom: formatAddress(sender),\n\t\tto: to.map(formatAddress),\n\t\tsubject: message.subject,\n\t\thtml: message.html,\n\t\ttext: message.text,\n\t\t...(message.replyTo === undefined\n\t\t\t? {}\n\t\t\t: {\n\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: Resend's wire format names the field, not us.\n\t\t\t\t\treply_to: formatAddress(message.replyTo),\n\t\t\t\t}),\n\t\t...(message.headers === undefined ||\n\t\tObject.keys(message.headers).length === 0\n\t\t\t? {}\n\t\t\t: { headers: message.headers }),\n\t\t...(message.attachments === undefined || message.attachments.length === 0\n\t\t\t? {}\n\t\t\t: {\n\t\t\t\t\tattachments: message.attachments.map((attachment) => ({\n\t\t\t\t\t\tfilename: attachment.filename,\n\t\t\t\t\t\tcontent: base64Of(attachment.content),\n\t\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: Resend's wire format names the field, not us.\n\t\t\t\t\t\tcontent_type: attachment.contentType,\n\t\t\t\t\t})),\n\t\t\t\t}),\n\t};\n}\n\n/** The largest delay a timer takes, 2³¹ − 1 ms — about 24.8 days. */\nconst MAX_TIMEOUT_MS = 2_147_483_647;\n\nconst text = (value: unknown) =>\n\ttypeof value === 'string' && value !== '' ? value : null;\n\nfunction checkOptions(options: ResendMailerOptions): void {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: options must be an object, as { apiKey }',\n\t\t);\n\t}\n\tif (typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey must be a Resend API key — is the environment variable set?',\n\t\t);\n\t}\n\tif (/\\s/.test(options.apiKey)) {\n\t\t// A key read from a file often keeps its final line break; `fetch`\n\t\t// would then refuse the header at every send, as an outage.\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey holds whitespace — trim the value it was read from',\n\t\t);\n\t}\n\tif (\n\t\toptions.baseUrl !== undefined &&\n\t\t(typeof options.baseUrl !== 'string' ||\n\t\t\t!/^https?:\\/\\/[^/]/.test(options.baseUrl))\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: baseUrl must be an http: or https: URL',\n\t\t);\n\t}\n\tif (options.fetch !== undefined && typeof options.fetch !== 'function') {\n\t\tthrow new TypeError('createResendMailer: fetch must be a function');\n\t}\n\tif (\n\t\toptions.timeoutMs !== undefined &&\n\t\t!(Number.isInteger(options.timeoutMs) && options.timeoutMs > 0)\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: timeoutMs must be a positive integer',\n\t\t);\n\t}\n\tif (options.timeoutMs !== undefined && options.timeoutMs > MAX_TIMEOUT_MS) {\n\t\t// A timer's delay is a signed 32-bit integer: above it, the runtime\n\t\t// fires at once, and every send would time out.\n\t\tthrow new TypeError(\n\t\t\t`createResendMailer: timeoutMs must be at most ${MAX_TIMEOUT_MS} — a longer timer fires at once`,\n\t\t);\n\t}\n\tif (options.from !== undefined) {\n\t\ttry {\n\t\t\tcheckMessage({ to: options.from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }',\n\t\t\t);\n\t\t}\n\t}\n}\n\n/** Creates a {@link Mailer} that sends each message through Resend's API. */\nexport function createResendMailer(options: ResendMailerOptions): Mailer {\n\tcheckOptions(options);\n\tconst endpoint = `${(options.baseUrl ?? 'https://api.resend.com').replace(/\\/+$/, '')}/emails`;\n\tconst post =\n\t\toptions.fetch ??\n\t\t((url: string, init: RequestInit) => globalThis.fetch(url, init));\n\tconst timeoutMs = options.timeoutMs ?? 30_000;\n\n\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? options.from;\n\t\t\tif (sender === undefined) {\n\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t'send: from is missing — give the message a from, or createResendMailer a default one',\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst body = bodyOf(message, sender);\n\n\t\t\tconst signal = AbortSignal.timeout(timeoutMs);\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await beforeAbort(\n\t\t\t\t\tpost(endpoint, {\n\t\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\t\theaders: {\n\t\t\t\t\t\t\tauthorization: `Bearer ${options.apiKey}`,\n\t\t\t\t\t\t\t'content-type': 'application/json',\n\t\t\t\t\t\t\t...(message.idempotencyKey === undefined\n\t\t\t\t\t\t\t\t? {}\n\t\t\t\t\t\t\t\t: { 'idempotency-key': message.idempotencyKey }),\n\t\t\t\t\t\t},\n\t\t\t\t\t\tbody: JSON.stringify(body),\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t}),\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof DOMException && error.name === 'TimeoutError') {\n\t\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t\t`send: Resend did not answer within ${timeoutMs} ms`,\n\t\t\t\t\t\t{ cause: error },\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure('send: Resend could not be reached', {\n\t\t\t\t\tcause: error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst answer = await readAnswer(response, signal);\n\t\t\tif (response.ok) return { messageId: text(answer.id) };\n\n\t\t\tconst cause = resendAnswer(\n\t\t\t\tresponse.status,\n\t\t\t\ttext(answer.name),\n\t\t\t\ttext(answer.message),\n\t\t\t);\n\t\t\t// 400 and 422 are Resend refusing the message, 413 a request too large\n\t\t\t// to take, and a 409 invalid_idempotent_request an idempotency key\n\t\t\t// already used for another message: sending again cannot fix any of\n\t\t\t// them. Anything else — a key refused, a rate limit, an outage, a 409\n\t\t\t// for a send with the same key still in progress — is Resend failing\n\t\t\t// to take it.\n\t\t\tif (\n\t\t\t\tresponse.status === 400 ||\n\t\t\t\tresponse.status === 413 ||\n\t\t\t\tresponse.status === 422 ||\n\t\t\t\t(response.status === 409 &&\n\t\t\t\t\tcause.errorName === 'invalid_idempotent_request')\n\t\t\t) {\n\t\t\t\tthrow new MailRefused('send: Resend refused the message', { cause });\n\t\t\t}\n\t\t\tthrow new MailFailure('send: Resend could not take the message', {\n\t\t\t\tcause,\n\t\t\t});\n\t\t},\n\t};\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "DBE3D2F49402DA0764756E2164756E21",
+  "mappings": "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",
+  "debugId": "BC85082B780FD90964756E2164756E21",
   "names": []
 }

package/docs/README.md

@@ -7,7 +7,7 @@ mailer, transport, hand-over, refusal, failure — are defined once, in the
 
 | Page | Read it when |
 | --- | --- |
-| [Setting up](guide/setup.md) | You are wiring `createResendMailer`: the key, the default sender, a proxy or another `baseUrl`, your own `fetch`, the timeout, and the request each message becomes |
+| [Setting up](guide/setup.md) | You are wiring `createResendMailer`: the key, the default sender, a proxy or another `baseUrl`, your own `fetch`, the timeout, the request each message becomes, and the idempotency key |
 | [Errors](guide/errors.md) | You are handling what `send` throws: which Resend answers are a `MailRefused`, which a `MailFailure`, what is on `cause`, and every `TypeError` at wiring |
 | [Testing](guide/testing.md) | You are testing the transport against a local server answering as Resend does, with `describeMailer` — or an application that uses it |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |

package/docs/guide/errors.md

@@ -47,6 +47,8 @@ Resend answers an error as `{ statusCode, name, message }`:
 | `400` | `validation_error` | `MailRefused` |
 | `413` | — (not in Resend's reference: a request too large for what sits in front of the API; refused, as a resend would fail again) | `MailRefused` |
 | `422` | `validation_error`, `missing_required_field`, `invalid_attachment` | `MailRefused` |
+| `409` | `invalid_idempotent_request` — the `idempotencyKey` was already used, within 24 hours, for a different message | `MailRefused` |
+| `409` | `concurrent_idempotent_requests` — a send with the same key is still in progress | `MailFailure` |
 | `401`, `403` | `missing_api_key`, `invalid_api_key`, an unverified domain | `MailFailure` |
 | `429` | `rate_limit_exceeded`, `daily_quota_exceeded` | `MailFailure` |
 | `5xx` | `internal_server_error` | `MailFailure` |
@@ -58,6 +60,26 @@ A `401` or `403` is a failure although it is a `4xx`: a bad key or an
 unverified domain refuses every message alike. It is the wiring that is
 wrong, not the message.
 
+A `409` is decided by its `name`. `invalid_idempotent_request` is a refusal:
+the key names another e-mail, and sending this one again under it fails
+again — give it its own key. `concurrent_idempotent_requests` is a failure:
+the first send with that key has not finished, and a retry later answers
+its id. See [Setting up — the idempotency key](setup.md#the-idempotency-key).
+
+```ts
+import { MailError, MailRefused } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	const cause = error instanceof MailError ? (error.cause as { status?: number; errorName?: string | null }) : undefined;
+	if (error instanceof MailRefused && cause?.errorName === 'invalid_idempotent_request') {
+		// a bug in how keys are derived: two different e-mails were given the same one
+	}
+	throw error;
+}
+```
+
 ## What `cause` holds
 
 For an answer, `cause` is a plain `Error` — the transport defines no class —
@@ -96,8 +118,8 @@ hold one.
 
 | `message` | Class | When |
 | --- | --- | --- |
-| `send: Resend refused the message` | `MailRefused` | A `400`, `413` or `422` |
-| `send: Resend could not take the message` | `MailFailure` | Any other answer that is not `2xx` |
+| `send: Resend refused the message` | `MailRefused` | A `400`, `413` or `422`, or a `409 invalid_idempotent_request` |
+| `send: Resend could not take the message` | `MailFailure` | Any other answer that is not `2xx` — a `409 concurrent_idempotent_requests` included |
 | `send: Resend could not be reached` | `MailFailure` | `fetch` threw |
 | `send: Resend did not answer within <timeoutMs> ms` | `MailFailure` | The timeout aborted the request |
 | `send: from is missing — give the message a from, or createResendMailer a default one` | `MailRefused` | A message without `from`, on a mailer without a default. No request is made |

package/docs/guide/setup.md

@@ -205,6 +205,70 @@ Content-Type: application/json
 `send` answers `{ messageId }`: Resend's `id`, or `null` when a `2xx` answer
 carries none, or is not JSON — the message was accepted, the id is absent.
 
+## The idempotency key
+
+A message's `idempotencyKey` is sent as Resend's `Idempotency-Key` header —
+never in the JSON body, so it never reaches the e-mail — and a message
+without one sends no such header:
+
+```ts
+await mailer.send({
+	to: 'ada@example.com',
+	subject: 'Your receipt',
+	html: '<p>Thank you for your order.</p>',
+	text: 'Thank you for your order.',
+	idempotencyKey: 'order-42/receipt',
+});
+```
+
+```http
+POST /emails HTTP/1.1
+Host: api.resend.com
+Authorization: Bearer re_…
+Content-Type: application/json
+Idempotency-Key: order-42/receipt
+
+{ "from": "\"Acme\" <noreply@acme.test>", "to": ["ada@example.com"], "subject": "Your receipt", … }
+```
+
+Resend remembers a key for **24 hours**. What it answers a second request
+with the same key:
+
+| The second request | Resend answers | `send` |
+| --- | --- | --- |
+| the same message, after the first was accepted | `200`, the first send's `id` | resolves with that `messageId`; nothing more is delivered |
+| a different message — another subject, recipient, attachment | `409 invalid_idempotent_request` | rejects with `MailRefused`: sending it again fails again. Give that e-mail its own key |
+| any message, while the first is still in progress | `409 concurrent_idempotent_requests` | rejects with `MailFailure`: retry later, with the same key |
+| any message, more than 24 hours later | a new send | resolves with a new id: the e-mail is delivered again |
+
+Derive the key from what the e-mail is about — `order-42/receipt`,
+`user-7/welcome` — never from the time or a random value, or every retry
+carries a new key. `checkMessage` refuses a key that is not 1 to 256 visible
+ASCII characters, before any request. The transport itself retries nothing:
+the key is what makes **your** retry safe.
+
+A job that retries after a failure, with the key it was queued with:
+
+```ts
+import { MailFailure, type MailMessage } from '@nxgt/mail';
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '', from: 'noreply@acme.test' });
+
+// Yours: the queue that runs a job again later — well within 24 hours.
+declare function retryIn(seconds: number): Promise<void>;
+
+export async function sendReceiptJob(order: { id: string; email: string }, rendered: Omit<MailMessage, 'to'>): Promise<void> {
+	try {
+		await mailer.send({ ...rendered, to: order.email, idempotencyKey: `order-${order.id}/receipt` });
+	} catch (error) {
+		// A timeout, a 5xx, a 409 still in progress: the same key, later, delivers at most once.
+		if (error instanceof MailFailure) return retryIn(60);
+		throw error; // MailRefused: fix the message, or its key
+	}
+}
+```
+
 ## With the renderer
 
 ```ts

package/docs/guide/testing.md

@@ -135,6 +135,13 @@ add what the suite does not ask of every transport:
 
 - a `400` and a `413` are a `MailRefused`; a `403`, a `429` and a `503` are a `MailFailure`
   with the status on `cause`, each tried once;
+- a `409 invalid_idempotent_request` — a key sent again with another
+  message — is a `MailRefused`, and a `409 concurrent_idempotent_requests` a
+  `MailFailure`, both with `status` and `errorName` on `cause`;
+- `idempotencyKey` is sent as the `Idempotency-Key` header, never in the
+  body, and no header is sent without one; a retry with the same key
+  answers the first id and delivers once, as the local server keeps keys as
+  Resend does;
 - a server that is not listening ends in `MailFailure` —
   `send: Resend could not be reached` — with the `fetch` error as `cause`;
 - a server that does not answer within `timeoutMs` ends in `MailFailure`, a

package/docs/roadmap.md

@@ -5,12 +5,13 @@ no dates here, and the version something shipped in is the only number.
 
 ## Now
 
-- **Attachments** — the `attachments` of a message are sent in Resend's
-  `attachments`, each as `{ filename, content, content_type }` with the bytes
-  in base64, encoded with no Node built-in so the transport still runs on an
-  edge runtime. Resend's `path` (a URL it would fetch) is never used. A
-  request too large (`413`) is a `MailRefused`, as a `400` or `422` is. Needs
-  `@nxgt/mail` 0.2. Built, not yet published.
+- **An idempotency key per send** — a message's `idempotencyKey` is sent as
+  Resend's `Idempotency-Key` header, so a retry the caller decides, within
+  Resend's 24 hours, answers the first send's id and cannot send the same
+  e-mail twice. A `409 invalid_idempotent_request` (the key already used for
+  another message) is a `MailRefused`; a `409 concurrent_idempotent_requests`
+  (the same key still in progress) stays a `MailFailure`. Needs `@nxgt/mail`
+  0.3. Built, not yet published.
 
 ## Next
 
@@ -18,8 +19,6 @@ Nothing yet.
 
 ## Later
 
-- **An idempotency key per send** — Resend's `Idempotency-Key` header, so a
-  retry the caller decides cannot send the same e-mail twice.
 - **Tags** — Resend's `tags`, to group sends in its dashboard.
 
 ## Not planned
@@ -39,6 +38,12 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Attachments, v0.2.0** — the `attachments` of a message are sent in Resend's
+  `attachments`, each as `{ filename, content, content_type }` with the bytes
+  in base64, encoded with no Node built-in so the transport still runs on an
+  edge runtime. Resend's `path` (a URL it would fetch) is never used. A
+  request too large (`413`) is a `MailRefused`, as a `400` or `422` is. Needs
+  `@nxgt/mail` 0.2.
 - **A Resend transport over `fetch`, v0.1.0** — `createResendMailer({ apiKey, from })`:
   one `POST /emails` per message, no SDK, no dependency, no Node built-in, so
   it runs on an edge runtime too. Each message is checked as every transport

package/docs/troubleshooting.md

@@ -55,10 +55,15 @@ A `MailRefused`, code `MAIL_REFUSED`.
 an address in a form it refuses, a header it does not allow, a subject too
 long, an attachment it will not carry (a `422` `invalid_attachment`, over
 40 MB once encoded in base64 included, a third larger than the files) — or a
-`413`, a request too large for what sits in front of the API.
+`413`, a request too large for what sits in front of the API. Or a `409`
+`invalid_idempotent_request`: the message's `idempotencyKey` was already used,
+within Resend's 24 hours, for a different message — a key per user rather
+than per e-mail, or a template, a variable or a recipient that changed
+between two attempts at the same e-mail.
 
 **Why:** Resend will refuse the same message again; retrying it unchanged is
-pointless.
+pointless. For a `409`, the first message with that key was taken; this one
+was not, and will not be under that key.
 
 **Fix:** read `cause.errorName` and `cause.detail` — Resend's own words:
 
@@ -75,6 +80,10 @@ try {
 			detail?: string | null;
 		};
 		console.warn(status, errorName, detail); // 422 validation_error Invalid `to` field. …
+		if (status === 409 && errorName === 'invalid_idempotent_request') {
+			// The key already named another message: it is not one key per e-mail.
+			console.warn('idempotencyKey reused for a different message');
+		}
 	}
 	throw error;
 }
@@ -86,6 +95,18 @@ For a message too large (`cause.status` `413`, or a `422` whose `detail`
 names the size), sending it again fails again: send the file as a signed
 link in the template instead of an attachment.
 
+For an `invalid_idempotent_request`, make the key name one e-mail — derived
+from what it is about, the same on every attempt at it — and render that
+e-mail the same way on every attempt:
+
+```ts
+await mailer.send({ ...message, idempotencyKey: `user-${user.id}` }); // ✗ every e-mail to that user
+await mailer.send({ ...message, idempotencyKey: `order-${order.id}/receipt` }); // ✓ this e-mail
+```
+
+A message that was meant to be different — a corrected receipt — is a new
+e-mail: give it a new key (`order-42/receipt-2`).
+
 ### `send: Resend could not take the message`
 
 A `MailFailure`, code `MAIL_FAILED`. **Nothing is known to have been sent**:
@@ -98,11 +119,30 @@ a server that accepted it before failing.
 | --- | --- | --- |
 | `401` | No key reached Resend | Check the key the process was started with |
 | `403` | An invalid or revoked key; a sending domain not verified; a test key sending to someone else than the account's owner | Check the key, and verify the `from` domain in Resend |
+| `409` `concurrent_idempotent_requests` | A send with the same `idempotencyKey` is still in progress — a retry, or a second worker, that started before the first attempt finished | Retry later, with the same key: once the first finishes, the retry answers its id |
 | `429` | The rate limit or the daily quota | Send less often, or from a queue that spaces the sends |
 | `5xx` | Resend is failing | Retry later |
 
 The transport does not retry: a retry is yours to decide, where you can see
-it.
+it. With an `idempotencyKey`, a retry of the same message within 24 hours is
+safe: if the first attempt went through, Resend answers its id and delivers
+nothing more.
+
+```ts
+import { MailFailure } from '@nxgt/mail';
+
+try {
+	await mailer.send({ ...message, idempotencyKey: `order-${order.id}/receipt` });
+} catch (error) {
+	const errorName = error instanceof MailFailure
+		? (error.cause as { errorName?: string | null } | undefined)?.errorName
+		: undefined;
+	if (errorName === 'concurrent_idempotent_requests') {
+		// The first attempt is still running: retry later, with the same key.
+	}
+	throw error;
+}
+```
 
 ### `send: Resend could not be reached`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail-resend",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "A Resend transport for @nxgt/mail over fetch, with no SDK: it throws the MailFailure and MailRefused of its @nxgt/mail peer, and passes the conformance suite.",
 	"license": "MIT",
 	"type": "module",
@@ -43,11 +43,11 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@nxgt/mail": "0.2.0",
+		"@nxgt/mail": "0.3.0",
 		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {
-		"@nxgt/mail": "^0.2.0",
+		"@nxgt/mail": "^0.3.0",
 		"typescript": "^6.0.3"
 	}
 }