@remit/smtp-worker 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/smtp-worker",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -16,7 +16,7 @@
   "scripts": {
     "bundle": "node build.mjs",
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=97 --test 'src/**/*.test.ts'",
+    "test:run": "node $NODE_TEST_FLAGS --env-file=../../localhost-test-unit.env --experimental-test-module-mocks --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=83 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run",
     "dev": "node --import tsx src/e2e-processor-shim.ts"
   },

package/src/handlers/send-message-core.ts

@@ -5,7 +5,7 @@ import type {
 	UpdateOutboxMessageInput,
 } from "@remit/data-ports";
 import { AccountAuthType, OutboxMessageStatus } from "@remit/domain-enums";
-import type { Logger } from "@remit/logger-lambda";
+import { type Logger, recordSmtpFailure } from "@remit/logger-lambda";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import type { SecretsService } from "@remit/secrets-service";
 import {
@@ -93,16 +93,70 @@ export interface SendMessageDeps {
 const UNFILED_NOT_QUEUED =
 	"Sent, but not filed: the copy for the Sent folder could not be queued.";
 
+const UNFILED_CONNECTION_LOST =
+	"The connection to the outgoing server dropped during the send, so this message may already have been delivered. Check with the recipient before sending it again.";
+
+/**
+ * The connection failures that prove nothing was submitted: no session ever
+ * opened, so the server holds no copy and `failed` is safe — Retry sends the
+ * only copy there is.
+ *
+ * `ECONNRESET` and `ETIMEDOUT` classify as `network` too and are deliberately
+ * absent. Either can land after DATA, with the message already queued on the
+ * server, and a `failed` row invites a Retry that delivers it twice.
+ */
+const NEVER_SUBMITTED_CODES: ReadonlySet<string> = new Set([
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EHOSTUNREACH",
+]);
+
+const errorCode = (cause: unknown): string =>
+	cause instanceof Error && "code" in cause && typeof cause.code === "string"
+		? cause.code
+		: "";
+
+/**
+ * Whether the message can be re-sent without risking a second copy. An auth
+ * rejection is decided before the envelope; a connection failure carries the
+ * code that says how far it got. Anything else counts as possibly delivered,
+ * which is the answer that cannot produce a duplicate.
+ */
+const neverSubmitted = (err: SmtpConnectionError): boolean =>
+	err.kind === "auth" || NEVER_SUBMITTED_CODES.has(errorCode(err.cause));
+
 const SENDABLE_STATUSES: ReadonlySet<OutboxMessageItem["status"]> = new Set([
 	OutboxMessageStatus.draft,
 	OutboxMessageStatus.queued,
 	OutboxMessageStatus.sending,
 ]);
 
+/**
+ * Fallback when `SEND_MESSAGE_MAX_ATTEMPTS` is unset (local dev, unit tests).
+ * Matches `remit-smtp`'s `maxReceiveCount` (`deploy/vps/queues.json`), same
+ * pattern as `MESSAGE_MOVE_MAX_ATTEMPTS` / `FLAG_PUSH_MAX_ATTEMPTS` in
+ * imap-worker.
+ */
+const DEFAULT_SEND_MESSAGE_MAX_ATTEMPTS = 3;
+
+export const getSendMessageMaxAttempts = (
+	processEnv: NodeJS.ProcessEnv = process.env,
+): number => {
+	const raw = processEnv.SEND_MESSAGE_MAX_ATTEMPTS;
+	if (!raw) return DEFAULT_SEND_MESSAGE_MAX_ATTEMPTS;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) && parsed > 0
+		? parsed
+		: DEFAULT_SEND_MESSAGE_MAX_ATTEMPTS;
+};
+
+export const SEND_MESSAGE_MAX_ATTEMPTS = getSendMessageMaxAttempts();
+
 export const sendMessage = async (
 	event: SendMessageEvent,
 	log: Logger,
 	deps: SendMessageDeps,
+	receiveCount = 1,
 ): Promise<void> => {
 	const { outboxMessageId, accountId } = event;
 
@@ -207,12 +261,12 @@ export const sendMessage = async (
 	} catch (err) {
 		// A terminal SMTP auth rejection (e.g. expired OAuth token surfaced at
 		// connect time) flips the account to reauth_required and ACKs.
-		// Only OAuth accounts have a re-auth recovery path. For password
-		// accounts, rethrow to preserve pre-PR batch-item-failure behaviour.
-		if (err instanceof SmtpConnectionError && err.kind === "auth") {
-			if (account.authType !== AccountAuthType.OauthMicrosoft) {
-				throw err;
-			}
+		// Only OAuth accounts have a re-auth recovery path.
+		if (
+			err instanceof SmtpConnectionError &&
+			err.kind === "auth" &&
+			account.authType === AccountAuthType.OauthMicrosoft
+		) {
 			log.warn(
 				{ accountId, errorKind: err.kind },
 				"SMTP auth rejected during send; marking account reauth_required",
@@ -220,6 +274,42 @@ export const sendMessage = async (
 			await deps.updateConnectionState(accountId, "reauth_required");
 			return; // ACK — do not retry
 		}
+		// A password account's auth failure and every network failure retry on
+		// SQS redelivery until the queue's own budget runs out, then settle
+		// here instead of dead-lettering with the row stuck at `sending`
+		// (issue #951). Where it settles is the double-send question:
+		// `neverSubmitted` says the message cannot be on the server, so
+		// `failed` offers the Retry the user needs; anything else settles
+		// `unfiled`, the state that says a copy may be out there and which
+		// Retry is not offered on. Wait-or-reconcile
+		// (docs/architecture/imap-mutations.md R2): neither applies — a
+		// submission leaves no server-side handle to reconcile against, so the
+		// row settles on what the failure itself proves.
+		if (err instanceof SmtpConnectionError) {
+			if (receiveCount < SEND_MESSAGE_MAX_ATTEMPTS) {
+				throw err;
+			}
+			const settled = neverSubmitted(err)
+				? { status: OutboxMessageStatus.failed, lastError: err.message }
+				: {
+						status: OutboxMessageStatus.unfiled,
+						lastError: `${UNFILED_CONNECTION_LOST} (${err.message})`,
+					};
+			await deps.updateOutbox(accountConfigId, outboxMessageId, settled);
+			// Terminal and never re-thrown, so the handler-outcome series
+			// records this record as a success. Counted here or it is invisible.
+			recordSmtpFailure(err.kind);
+			log.error(
+				{
+					outboxMessageId,
+					errorKind: err.kind,
+					receiveCount,
+					status: settled.status,
+				},
+				"SMTP send retry exhausted; settling the row",
+			);
+			return; // ACK — settled terminal, no more retries
+		}
 		throw err;
 	}
 
@@ -265,16 +355,41 @@ export const sendMessage = async (
 	}
 
 	if (result.isTransient) {
-		log.warn(
+		// A 4xx from the server is retried on SQS redelivery the same way a
+		// connection failure is above; once the queue's own budget runs out
+		// this settles the row at `failed` rather than leaving it at `queued`
+		// forever once the record dead-letters (issue #951).
+		if (receiveCount < SEND_MESSAGE_MAX_ATTEMPTS) {
+			log.warn(
+				{
+					outboxMessageId,
+					smtpCode: result.smtpCode,
+					error: result.error?.message,
+				},
+				"Transient failure, will retry",
+			);
+			await deps.updateOutboxStatus(accountConfigId, outboxMessageId, "queued");
+			throw new Error(`SMTP transient error: ${result.error?.message}`);
+		}
+
+		await deps.updateOutbox(accountConfigId, outboxMessageId, {
+			status: "failed",
+			lastError: result.error?.message,
+			lastSmtpCode: result.smtpCode,
+		});
+		// Terminal and never re-thrown, so the handler-outcome series records
+		// this record as a success. Counted here or it is invisible.
+		recordSmtpFailure("other");
+		log.error(
 			{
 				outboxMessageId,
 				smtpCode: result.smtpCode,
 				error: result.error?.message,
+				receiveCount,
 			},
-			"Transient failure, will retry",
+			"Transient failure retry exhausted; settling as failed",
 		);
-		await deps.updateOutboxStatus(accountConfigId, outboxMessageId, "queued");
-		throw new Error(`SMTP transient error: ${result.error?.message}`);
+		return;
 	}
 
 	// Permanent failure - mark as failed, don't throw (no retry)

package/src/handlers/send-message.test.ts

@@ -13,7 +13,12 @@ import {
 } from "@remit/secrets-service";
 import { type SendResult, SmtpConnectionError } from "@remit/smtp-service";
 import type { SendMessageEvent } from "../events.js";
-import { type SendMessageDeps, sendMessage } from "./send-message-core.js";
+import {
+	getSendMessageMaxAttempts,
+	SEND_MESSAGE_MAX_ATTEMPTS,
+	type SendMessageDeps,
+	sendMessage,
+} from "./send-message-core.js";
 
 const silentLogger = {
 	info: () => {},
@@ -324,6 +329,24 @@ describe("sendMessage handler", () => {
 		assert.equal(recorded.updates.length, 0);
 	});
 
+	it("drops the event for a row the enqueue settled at `failed`", async () => {
+		// The other half of #936. An error from SQS `SendMessage` says the response
+		// was lost, not that the broker refused the event, so the row is settled
+		// outside this fence and the event that landed anyway dies here. Settling
+		// it at `draft` instead would send it — and leave the user a row they can
+		// send a second time.
+		const { deps, recorded } = buildDeps({
+			outbox: buildOutbox({ status: "failed" }),
+		});
+
+		await sendMessage(event, silentLogger, deps);
+
+		assert.equal(recorded.sendCalls, 0, "must not send");
+		assert.equal(recorded.marked.length, 0);
+		assert.equal(recorded.updates.length, 0);
+		assert.equal(recorded.statuses.length, 0);
+	});
+
 	it("settles the row as unfiled when the append event cannot be queued", async () => {
 		const { deps, recorded } = buildDeps({
 			account: buildAccount({ smtpHost: "smtp.example.com", smtpPort: 587 }),
@@ -653,3 +676,179 @@ describe("sendMessage OAuth reauth/ACK contract", () => {
 		);
 	});
 });
+
+/**
+ * A connection failure as `smtp-client.ts` raises one: the code nodemailer put
+ * on the underlying error is what says how far the submission got, and it
+ * survives only on the cause.
+ */
+const connectionError = (code: string): SmtpConnectionError =>
+	new SmtpConnectionError(
+		"network",
+		`SMTP connection failed: ${code}`,
+		Object.assign(new Error(code), { code }),
+	);
+
+describe("sendMessage retry-budget exhaustion (issue #951)", () => {
+	it("rethrows a password account's auth failure below the retry budget, leaving the row `sending`", async () => {
+		const { deps, recorded } = buildDeps({
+			account: buildAccount({
+				smtpHost: "smtp.example.com",
+				smtpPort: 587,
+				authType: AccountAuthType.Password,
+			}),
+			send: async () => {
+				throw new SmtpConnectionError("auth", "535 authentication failed");
+			},
+		});
+
+		await assert.rejects(
+			() =>
+				sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS - 1),
+			/535 authentication failed/,
+		);
+		assert.equal(
+			recorded.updates.length,
+			0,
+			"must not settle the row before the retry budget is spent",
+		);
+	});
+
+	it("settles a password account's exhausted auth failure at `failed`, not stranded at `sending`", async () => {
+		const { deps, recorded } = buildDeps({
+			account: buildAccount({
+				smtpHost: "smtp.example.com",
+				smtpPort: 587,
+				authType: AccountAuthType.Password,
+			}),
+			send: async () => {
+				throw new SmtpConnectionError("auth", "535 authentication failed");
+			},
+		});
+
+		await sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS);
+
+		assert.equal(recorded.connectionStateUpdates.length, 0);
+		const failedUpdate = recorded.updates.find(
+			(u) => u.patch.status === "failed",
+		);
+		assert.ok(failedUpdate, "should settle the row as failed");
+		assert.match(String(failedUpdate.patch.lastError), /authentication failed/);
+	});
+
+	it("settles an exhausted refused connection at `failed`, not stranded at `sending`", async () => {
+		const { deps, recorded } = buildDeps({
+			account: buildAccount({ smtpHost: "smtp.example.com", smtpPort: 587 }),
+			send: async () => {
+				throw connectionError("ECONNREFUSED");
+			},
+		});
+
+		await sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS);
+
+		const failedUpdate = recorded.updates.find(
+			(u) => u.patch.status === "failed",
+		);
+		assert.ok(failedUpdate, "should settle the row as failed");
+		assert.match(String(failedUpdate.patch.lastError), /ECONNREFUSED/);
+	});
+
+	for (const code of ["ECONNRESET", "ETIMEDOUT"]) {
+		it(`settles an exhausted ${code} at \`unfiled\` — the server may hold the message`, async () => {
+			// Both classify as `network` and both can land after DATA, so a
+			// `failed` row here would offer a Retry that delivers a second copy.
+			const { deps, recorded } = buildDeps({
+				account: buildAccount({ smtpHost: "smtp.example.com", smtpPort: 587 }),
+				send: async () => {
+					throw connectionError(code);
+				},
+			});
+
+			await sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS);
+
+			assert.equal(
+				recorded.updates.find((u) => u.patch.status === "failed"),
+				undefined,
+				"a row that may have been delivered must not be re-sendable",
+			);
+			const settled = recorded.updates.at(-1)?.patch;
+			assert.equal(settled?.status, "unfiled");
+			assert.match(
+				String(settled?.lastError),
+				/may already have been delivered/,
+			);
+			assert.match(String(settled?.lastError), new RegExp(code));
+		});
+	}
+
+	it("settles an exhausted connection failure that names no code at `unfiled`", async () => {
+		// Nothing says the message did not reach the server, and the answer that
+		// cannot produce a second copy is the one to settle on.
+		const { deps, recorded } = buildDeps({
+			account: buildAccount({ smtpHost: "smtp.example.com", smtpPort: 587 }),
+			send: async () => {
+				throw new SmtpConnectionError("network", "SMTP connection failed");
+			},
+		});
+
+		await sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS);
+
+		assert.equal(recorded.updates.at(-1)?.patch.status, "unfiled");
+	});
+
+	it("settles an exhausted transient SMTP failure at `failed` instead of leaving it `queued` forever", async () => {
+		const { deps, recorded } = buildDeps({
+			account: buildAccount({ smtpHost: "smtp.example.com", smtpPort: 587 }),
+			sendResult: {
+				success: false,
+				error: new Error("temporarily unavailable"),
+				smtpCode: 421,
+				isTransient: true,
+			},
+		});
+
+		await sendMessage(event, silentLogger, deps, SEND_MESSAGE_MAX_ATTEMPTS);
+
+		const failedUpdate = recorded.updates.find(
+			(u) => u.patch.status === "failed",
+		);
+		assert.ok(failedUpdate, "should settle the row as failed");
+		assert.equal(failedUpdate.patch.lastSmtpCode, 421);
+		assert.equal(
+			recorded.statuses.find((s) => s.status === "queued"),
+			undefined,
+			"must not leave the row requeued once the budget is spent",
+		);
+	});
+});
+
+describe("the retry budget is the queue's, read from the environment", () => {
+	it("takes the deployment's own maxReceiveCount when it is set", () => {
+		// The e2e stack sets 1 (`deploy/vps/e2e.env`): its pollers hold a record
+		// for 300s, so a spec cannot wait out three deliveries.
+		assert.equal(
+			getSendMessageMaxAttempts({ SEND_MESSAGE_MAX_ATTEMPTS: "1" }),
+			1,
+		);
+		assert.equal(
+			getSendMessageMaxAttempts({ SEND_MESSAGE_MAX_ATTEMPTS: "5" }),
+			5,
+		);
+	});
+
+	it("falls back to remit-smtp's maxReceiveCount when it is unset or unusable", () => {
+		assert.equal(getSendMessageMaxAttempts({}), 3);
+		assert.equal(
+			getSendMessageMaxAttempts({ SEND_MESSAGE_MAX_ATTEMPTS: "" }),
+			3,
+		);
+		assert.equal(
+			getSendMessageMaxAttempts({ SEND_MESSAGE_MAX_ATTEMPTS: "not-a-number" }),
+			3,
+		);
+		assert.equal(
+			getSendMessageMaxAttempts({ SEND_MESSAGE_MAX_ATTEMPTS: "0" }),
+			3,
+		);
+	});
+});

package/src/handlers/send-message.ts

@@ -132,50 +132,56 @@ const buildCredentialDeps = (): AccountCredentialsDeps => ({
 export const handleSendMessage = (
 	event: SendMessageEvent,
 	log: Logger,
+	receiveCount = 1,
 ): Promise<void> => {
 	const credentialDeps = buildCredentialDeps();
-	return sendMessage(event, log, {
-		getOutbox: async (accountConfigId, id) =>
-			(await getPorts()).outboxMessage.get(accountConfigId, id),
-		getAccount: async (id) => (await getPorts()).account.get(id),
-		updateOutbox: async (accountConfigId, id, patch) =>
-			(await getPorts()).outboxMessage.update(accountConfigId, id, patch),
-		updateOutboxStatus: async (accountConfigId, id, status) =>
-			(await getPorts()).outboxMessage.updateStatus(
-				accountConfigId,
-				id,
-				status,
-			),
-		markOutboxSent: async (accountConfigId, id, fields) =>
-			(await getPorts()).outboxMessage.markSent(accountConfigId, id, fields),
-		secrets,
-		resolveCredentials: (account) =>
-			resolveConnectionCredentials(account, credentialDeps),
-		updateConnectionState: async (id, state) => {
-			const { account } = await getPorts();
-			await account.update(id, {
-				connectionState:
-					state as (typeof ConnectionState)[keyof typeof ConnectionState],
-			});
-		},
-		send: sendMail,
-		emitAppendSentMessage,
-		engagement: {
-			resolveAddressId: deriveAddressId,
-			incrementOutboundCount: async (accountConfigId, addressId, now) =>
-				(await getPorts()).address.incrementOutboundCount(
-					accountConfigId,
-					addressId,
-					now,
-				),
-			incrementReplyCount: async (accountConfigId, addressId, now) =>
-				(await getPorts()).address.incrementReplyCount(
+	return sendMessage(
+		event,
+		log,
+		{
+			getOutbox: async (accountConfigId, id) =>
+				(await getPorts()).outboxMessage.get(accountConfigId, id),
+			getAccount: async (id) => (await getPorts()).account.get(id),
+			updateOutbox: async (accountConfigId, id, patch) =>
+				(await getPorts()).outboxMessage.update(accountConfigId, id, patch),
+			updateOutboxStatus: async (accountConfigId, id, status) =>
+				(await getPorts()).outboxMessage.updateStatus(
 					accountConfigId,
-					addressId,
-					now,
+					id,
+					status,
 				),
-			findMessageByHeader,
-			getEnvelopeFromEmail,
+			markOutboxSent: async (accountConfigId, id, fields) =>
+				(await getPorts()).outboxMessage.markSent(accountConfigId, id, fields),
+			secrets,
+			resolveCredentials: (account) =>
+				resolveConnectionCredentials(account, credentialDeps),
+			updateConnectionState: async (id, state) => {
+				const { account } = await getPorts();
+				await account.update(id, {
+					connectionState:
+						state as (typeof ConnectionState)[keyof typeof ConnectionState],
+				});
+			},
+			send: sendMail,
+			emitAppendSentMessage,
+			engagement: {
+				resolveAddressId: deriveAddressId,
+				incrementOutboundCount: async (accountConfigId, addressId, now) =>
+					(await getPorts()).address.incrementOutboundCount(
+						accountConfigId,
+						addressId,
+						now,
+					),
+				incrementReplyCount: async (accountConfigId, addressId, now) =>
+					(await getPorts()).address.incrementReplyCount(
+						accountConfigId,
+						addressId,
+						now,
+					),
+				findMessageByHeader,
+				getEnvelopeFromEmail,
+			},
 		},
-	});
+		receiveCount,
+	);
 };

package/src/index.test.ts

@@ -0,0 +1,93 @@
+/**
+ * The delivery count the settle decision is made on comes from the queue, and
+ * nothing between the record and the handler is allowed to drop it: a handler
+ * that always sees 1 never reaches the settle at all, and the row dead-letters
+ * at `sending` exactly as it did before #951.
+ *
+ * The send handler is replaced here, so this file is about the wiring and not
+ * about what the handler does with it — and replacing it is also what keeps
+ * the real one's data ports and queue producers out of a unit test.
+ */
+import assert from "node:assert/strict";
+import { describe, it, mock } from "node:test";
+import type { Context, SQSEvent } from "aws-lambda";
+
+const receiveCounts: number[] = [];
+
+mock.module("./handlers/send-message.js", {
+	namedExports: {
+		handleSendMessage: async (
+			_event: unknown,
+			_log: unknown,
+			receiveCount: number,
+		): Promise<void> => {
+			receiveCounts.push(receiveCount);
+		},
+	},
+});
+
+const { handler, parseReceiveCount } = await import("./index.js");
+
+const context = {
+	functionName: "smtp-worker-test",
+	awsRequestId: "req-1",
+} as Context;
+
+const sendMessageEvent = (approximateReceiveCount: string): SQSEvent =>
+	({
+		Records: [
+			{
+				messageId: "sqs-1",
+				receiptHandle: "rh-1",
+				body: JSON.stringify({
+					type: "SEND_MESSAGE",
+					eventId: "evt-1",
+					timestamp: 0,
+					accountId: "acc-1",
+					outboxMessageId: "obx-1",
+				}),
+				attributes: { ApproximateReceiveCount: approximateReceiveCount },
+				messageAttributes: {},
+				md5OfBody: "",
+				eventSource: "aws:sqs",
+				eventSourceARN: "http://queue:9324/000000000000/remit-smtp",
+				awsRegion: "local",
+			},
+		],
+	}) as unknown as SQSEvent;
+
+describe("parseReceiveCount — SQS ApproximateReceiveCount parsing", () => {
+	it("parses the raw string attribute", () => {
+		assert.equal(parseReceiveCount("1"), 1);
+		assert.equal(parseReceiveCount("3"), 3);
+	});
+
+	it("defaults to 1 when the attribute is missing", () => {
+		assert.equal(parseReceiveCount(undefined), 1);
+	});
+
+	it("defaults to 1 on a non-numeric or non-positive value", () => {
+		assert.equal(parseReceiveCount("not-a-number"), 1);
+		assert.equal(parseReceiveCount("0"), 1);
+		assert.equal(parseReceiveCount("-1"), 1);
+	});
+});
+
+describe("the record's delivery count reaches the send handler", () => {
+	it("threads ApproximateReceiveCount through the processor into handleSendMessage", async () => {
+		receiveCounts.length = 0;
+
+		const response = await handler(sendMessageEvent("3"), context);
+
+		assert.deepEqual(receiveCounts, [3]);
+		assert.deepEqual(response.batchItemFailures, []);
+	});
+
+	it("carries the first delivery through as 1", async () => {
+		receiveCounts.length = 0;
+
+		await handler(sendMessageEvent("1"), context);
+
+		assert.deepEqual(receiveCounts, [1]);
+	});
+});

package/src/index.ts

@@ -13,20 +13,36 @@ import { processEvent } from "./processor.js";
 
 const log = createLogger();
 
+/**
+ * Parse SQS's `ApproximateReceiveCount` record attribute (1 on first
+ * delivery). Missing/malformed defaults to 1 so a record with no attribute
+ * (e.g. an older local harness) is treated as a first attempt rather than
+ * skipping straight to retry-exhaustion handling. Mirrors
+ * `imap-worker/src/index.ts`'s `parseReceiveCount`.
+ */
+export const parseReceiveCount = (value: string | undefined): number => {
+	const parsed = Number.parseInt(value ?? "1", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+};
+
 export const handler = withTelemetry(
 	async (event: SQSEvent): Promise<SQSBatchResponse> => {
 		const batchItemFailures: { itemIdentifier: string }[] = [];
 
 		for (const record of event.Records) {
 			const smtpEvent: SmtpEvent = JSON.parse(record.body);
+			const receiveCount = parseReceiveCount(
+				record.attributes?.ApproximateReceiveCount,
+			);
 			log.info("Processing SMTP event", {
 				eventType: smtpEvent.type,
 				eventId: smtpEvent.eventId,
+				receiveCount,
 			});
 
 			const queue = queueNameFromEventSource(record.eventSourceARN);
 			const sendStart = Date.now();
-			const failed = await processEvent(smtpEvent, log)
+			const failed = await processEvent(smtpEvent, log, receiveCount)
 				.then(() => {
 					recordQueueEvent({
 						queue,

package/src/processor.ts

@@ -5,10 +5,18 @@ import { handleSendMessage } from "./handlers/send-message.js";
 export const processEvent = async (
 	event: SmtpEvent,
 	log: Logger,
+	/**
+	 * SQS's own delivery count for the record carrying this event (1 on first
+	 * delivery). Read by SEND_MESSAGE so it knows from it when this is the
+	 * last attempt before the queue's own redrive policy would DLQ the
+	 * record, so it can resolve retry exhaustion into a terminal outcome
+	 * (issue #951) instead of dead-lettering blindly.
+	 */
+	receiveCount = 1,
 ): Promise<void> => {
 	switch (event.type) {
 		case "SEND_MESSAGE":
-			return handleSendMessage(event, log);
+			return handleSendMessage(event, log, receiveCount);
 		case "PROCESS_OUTBOX":
 			// Future: batch process all queued messages
 			log.info(