@nxgt/mail-smtp 0.2.0 → 0.3.1

package/README.md

@@ -37,8 +37,8 @@ bun add @nxgt/mail-smtp @nxgt/mail nodemailer
 
 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.
 - `nodemailer` (`>=7 <11`; tested with 10). This package never imports it:
   you create the transporter, with every SMTP option nodemailer has.
@@ -76,7 +76,7 @@ await mailer.send({
 	to: [{ name: 'Doe, John', address: 'john@example.com' }],
 	from: 'billing@acme.test', // required here: this mailer has no default
 	replyTo: 'support@acme.test',
-	headers: { 'List-Unsubscribe': '<https://acme.test/unsubscribe>' },
+	headers: { 'X-Entity-Ref-ID': 'invoice-42' },
 	subject: 'Your invoice',
 	html: '<p>…</p>',
 	text: '…',
@@ -89,8 +89,15 @@ await mailer.send({
 - A name is handed to nodemailer as `{ name, address }`: nodemailer quotes and
   encodes it, so `Doe, John` names one recipient.
 - `messageId` is nodemailer's id (`<…@host>`), or `null` when it gives none.
+- For marketing mail, build `List-Unsubscribe` and `List-Unsubscribe-Post`
+  with `listUnsubscribe` from `@nxgt/mail` rather than by hand; your relay, or
+  nodemailer's `dkim` option, must DKIM-sign them — see
+  [one-click unsubscribe](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/sending.md#one-click-unsubscribe).
 - The parts are strings and the attachments bytes: nodemailer is told never
   to read a file or a URL (`disableFileAccess`, `disableUrlAccess`).
+- `idempotencyKey` is ignored: SMTP has no such mechanism, so a message sent
+  twice is delivered twice. See
+  [Setting up — the idempotency key](docs/guide/setup.md#the-idempotency-key).
 
 ### Attachments
 
@@ -170,6 +177,11 @@ A timeout ends in `MailFailure`.
 `539`) and a sender refused at `MAIL FROM`: the next message would be refused
 the same way, so it is a failure of the wiring, not of the message.
 
+**A retry after a timeout can deliver twice.** SMTP cannot deduplicate, and
+the transport ignores `idempotencyKey`: after a `MailFailure` from a
+timeout, the server may already have the message. Retry only what you can
+afford to send twice.
+
 **Some recipients refused still throws, after the others got it.** The
 server may accept one recipient and refuse another; the message then went out
 to the accepted one. Retrying it whole sends it to them twice — send to one

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 `createSmtpMailer` to a nodemailer transporter: host, port and TLS, credentials, a pool, timeouts, the default sender, and what a message becomes on the wire |
+| [Setting up](guide/setup.md) | You are wiring `createSmtpMailer` to a nodemailer transporter: host, port and TLS, credentials, a pool, timeouts, the default sender, what a message becomes on the wire, and why `idempotencyKey` is ignored (with Resend's SMTP relay header) |
 | [Errors](guide/errors.md) | You are handling what `send` throws: which SMTP 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 real SMTP server — `smtp-server`, `mailparser`, `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

@@ -19,7 +19,9 @@ recipients may already have the message. The message says so
 ([below](#some-recipients-refused)); retrying it whole sends it to them again.
 
 Nothing is retried. Whether and when to retry is yours to decide, where you
-can see it.
+can see it. SMTP cannot deduplicate — the transport ignores
+`idempotencyKey` — so a retry after a timeout may deliver the e-mail twice
+([Setting up — the idempotency key](setup.md#the-idempotency-key)).
 
 ```ts
 import { MailError, type MailErrorCode, type Mailer, type MailMessage } from '@nxgt/mail';

package/docs/guide/setup.md

@@ -171,7 +171,8 @@ A string is only an address: `'Acme <noreply@acme.test>'` is refused. Write
 | an `{ name, address }` | the same object: nodemailer quotes and encodes the name, so `Doe, John` or `Ada <mallory@example.test>` stays one recipient's name |
 | `from`, `replyTo` | `from`, `replyTo` |
 | `subject`, `html`, `text` | the same, as strings — the e-mail is `multipart/alternative` |
-| `headers` | `headers`, copied |
+| `headers` | `headers`, copied — `List-Unsubscribe` from [`listUnsubscribe`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/sending.md#one-click-unsubscribe) included, which your relay or nodemailer's `dkim` option must DKIM-sign |
+| `idempotencyKey` | nothing: ignored — see [below](#the-idempotency-key) |
 | `attachments`, each `{ filename, content, contentType }` | `attachments`, each `{ filename, content: Buffer, contentType }` — the bytes copied into a `Buffer`, never a `path` or an `href`; the e-mail is then `multipart/mixed`. Left out when the list is empty |
 | — | `disableFileAccess: true`, `disableUrlAccess: true`: a part or an attachment is never read from a file or fetched from a URL |
 
@@ -184,6 +185,52 @@ subject or the MIME structure (`Bcc`, `To`, `Content-Type`…). Its messages are
 `send` answers `{ messageId }`: nodemailer's `Message-ID` (`<…@acme.test>`), or
 `null` when the transporter answers none — an absence, not a failure.
 
+## The idempotency key
+
+SMTP has no idempotency: a server takes every message it is handed, and
+cannot tell a retry from a new e-mail. The transport therefore **ignores**
+`idempotencyKey` — it neither refuses the message nor writes the key into it
+— and a message sent twice is delivered twice:
+
+```ts
+const once = {
+	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', // still checked by checkMessage; not sent
+};
+
+await mailer.send(once);
+await mailer.send(once); // a second e-mail
+```
+
+Setting the key is still worth it when the same code may run on a
+transport that deduplicates, as `@nxgt/mail-resend`. Over SMTP, a retry
+after a `MailFailure` from a timeout or a dropped connection may deliver
+twice: the server may have taken the message before the connection ended.
+
+**Relaying through Resend's SMTP server** (`smtp.resend.com`)? Resend reads
+its own `Resend-Idempotency-Key` header there. The transport does not set it
+from `idempotencyKey`; set it yourself among the headers, with the same
+value:
+
+```ts
+const key = 'order-42/receipt';
+
+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: key,
+	headers: { 'Resend-Idempotency-Key': key }, // read by Resend's relay; any other server passes it on as a header
+});
+```
+
+On any other server, that header travels with the e-mail to the recipient:
+set it only when the relay is Resend's.
+
 ## Attachments
 
 ```ts

package/docs/guide/testing.md

@@ -155,6 +155,8 @@ add what the suite does not ask of every transport:
 - the default `from`, `replyTo` and `headers` reach the server, and the id is
   nodemailer's;
 - nodemailer is told never to read a file or a URL;
+- `idempotencyKey` is ignored: the same message sent twice is handed over
+  twice, and the key appears nowhere in what nodemailer receives;
 - attachments are handed over as `{ filename, content, contentType }` with a
   `Buffer` copied from the bytes — a change to the caller's array during the
   send reaches no one — and an empty list sends none;

package/docs/roadmap.md

@@ -5,12 +5,7 @@ no dates here, and the version something shipped in is the only number.
 
 ## Now
 
-- **Attachments** — the `attachments` of a message are handed to nodemailer
-  as bytes, a `Buffer` copied from each `Uint8Array`, with their file name
-  (encoded by nodemailer when it is not ASCII) and their type. Never a `path`
-  or an `href`: `disableFileAccess` and `disableUrlAccess` stay on. A message
-  over the server's size limit (`552`) is a `MailRefused`. Needs
-  `@nxgt/mail` 0.2. Built, not yet published.
+Nothing yet.
 
 ## Next
 
@@ -40,6 +35,16 @@ Nothing planned yet. Say what you need in an issue.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Messages with an idempotency key, v0.3.0** — a message that carries an
+  `idempotencyKey` is accepted, and the key is ignored: SMTP has no
+  idempotency, so a message sent twice is delivered twice. Needs `@nxgt/mail`
+  0.3.
+- **Attachments, v0.2.0** — the `attachments` of a message are handed to nodemailer
+  as bytes, a `Buffer` copied from each `Uint8Array`, with their file name
+  (encoded by nodemailer when it is not ASCII) and their type. Never a `path`
+  or an `href`: `disableFileAccess` and `disableUrlAccess` stay on. A message
+  over the server's size limit (`552`) is a `MailRefused`. Needs
+  `@nxgt/mail` 0.2.
 - **An SMTP transport on your nodemailer, v0.1.0** — `createSmtpMailer({ transporter,
   from })`: every SMTP option is nodemailer's, set where you create the
   transporter. Each message is checked as every transport checks it, a name is

package/docs/troubleshooting.md

@@ -79,6 +79,11 @@ try {
 A retry is yours to decide — from a queue, with a delay. The transport never
 retries in secret.
 
+An `idempotencyKey` does not make that retry safe here: SMTP has no
+idempotency, and this transport ignores the key. If the first attempt went
+through after all, the retry delivers a second copy — weigh that before
+retrying after a timeout.
+
 ### `send: the SMTP server refused the message`
 
 A `MailRefused`, code `MAIL_REFUSED`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail-smtp",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "An SMTP transport for @nxgt/mail, on the nodemailer you install: it throws the MailFailure and MailRefused of its @nxgt/mail peer, and passes the conformance suite.",
 	"license": "MIT",
 	"type": "module",
@@ -44,7 +44,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@nxgt/mail": "0.2.0",
+		"@nxgt/mail": "0.4.0",
 		"@types/bun": "^1.4.2",
 		"@types/mailparser": "^3.4.6",
 		"@types/nodemailer": "^8.0.2",
@@ -54,7 +54,7 @@
 		"smtp-server": "^3.19.13"
 	},
 	"peerDependencies": {
-		"@nxgt/mail": "^0.2.0",
+		"@nxgt/mail": "^0.4.0",
 		"nodemailer": ">=7.0.0 <11",
 		"typescript": "^6.0.3"
 	}