From c48819037e7cee1f9ceafc42b361fd97f9cbfd79 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Fri, 6 Nov 2026 23:15:46 -0500 Subject: [PATCH 1/2] Record why an email send was rejected or failed POST /api/emails rejected 59% of logged sends with nothing to say why: the rejected path stored only the raw body. validateSendEmailBody now returns a reason (short code then detail) and the account once auth has resolved it; sendEmailHandler passes both to logEmailAttempt, and the send_failed path records the Resend error. Needs the email_send_log.reason column (recoupable/database#132). Refs recoupable/app#1949 Co-Authored-By: Claude Opus 5.5 --- .../__tests__/emailFailureFallback.test.ts | 1 + lib/emails/__tests__/logEmailAttempt.test.ts | 17 +++++++ lib/emails/__tests__/sendEmailHandler.test.ts | 10 ++++- .../__tests__/validateSendEmailBody.test.ts | 44 +++++++++++++++++++ lib/emails/logEmailAttempt.ts | 3 ++ lib/emails/sendEmailHandler.ts | 9 +++- lib/emails/validateSendEmailBody.ts | 16 +++++-- types/database.types.ts | 3 ++ 8 files changed, 95 insertions(+), 8 deletions(-) diff --git a/lib/emails/__tests__/emailFailureFallback.test.ts b/lib/emails/__tests__/emailFailureFallback.test.ts index 8aee508c4..588d28a00 100644 --- a/lib/emails/__tests__/emailFailureFallback.test.ts +++ b/lib/emails/__tests__/emailFailureFallback.test.ts @@ -81,6 +81,7 @@ describe("email failure fallback through the real Resend adapter", () => { status: "send_failed", accountId: "synthetic-account", chatId: undefined, + reason: "resend_error: Failed to send email.", }); }); diff --git a/lib/emails/__tests__/logEmailAttempt.test.ts b/lib/emails/__tests__/logEmailAttempt.test.ts index 4026da1e5..fcdc3095b 100644 --- a/lib/emails/__tests__/logEmailAttempt.test.ts +++ b/lib/emails/__tests__/logEmailAttempt.test.ts @@ -33,6 +33,23 @@ describe("logEmailAttempt", () => { expect(row.raw_body).toBe(raw); }); + it("records why a send was rejected", async () => { + await logEmailAttempt({ + rawBody: "{}", + status: "rejected", + accountId: "acc-1", + reason: "no_account_email", + }); + const row = mockInsert.mock.calls[0][0]; + expect(row.reason).toBe("no_account_email"); + expect(row.account_id).toBe("acc-1"); + }); + + it("stores a null reason when none is given", async () => { + await logEmailAttempt({ rawBody: "{}", status: "sent" }); + expect(mockInsert.mock.calls[0][0].reason).toBeNull(); + }); + it("stores the full raw body (no truncation)", async () => { await logEmailAttempt({ rawBody: "x".repeat(20000), status: "rejected" }); expect(mockInsert.mock.calls[0][0].raw_body.length).toBe(20000); diff --git a/lib/emails/__tests__/sendEmailHandler.test.ts b/lib/emails/__tests__/sendEmailHandler.test.ts index 8bc132c14..15d63c279 100644 --- a/lib/emails/__tests__/sendEmailHandler.test.ts +++ b/lib/emails/__tests__/sendEmailHandler.test.ts @@ -85,12 +85,18 @@ describe("sendEmailHandler", () => { mockValidateSendEmailBody.mockResolvedValue({ rawBody: "{}", error: NextResponse.json({ status: "error", error: "Forbidden" }, { status: 403 }), + reason: "recipient_not_allowed: stranger@example.com", + accountId: "account-123", }); const response = await sendEmailHandler(createRequest()); expect(response.status).toBe(403); expect(mockProcessAndSendEmail).not.toHaveBeenCalled(); expect(mockLogEmailAttempt).toHaveBeenCalledWith( - expect.objectContaining({ status: "rejected" }), + expect.objectContaining({ + status: "rejected", + reason: "recipient_not_allowed: stranger@example.com", + accountId: "account-123", + }), ); }); @@ -101,7 +107,7 @@ describe("sendEmailHandler", () => { const json = await response.json(); expect(json.error).toBe("resend boom"); expect(mockLogEmailAttempt).toHaveBeenCalledWith( - expect.objectContaining({ status: "send_failed" }), + expect.objectContaining({ status: "send_failed", reason: "resend_error: resend boom" }), ); }); }); diff --git a/lib/emails/__tests__/validateSendEmailBody.test.ts b/lib/emails/__tests__/validateSendEmailBody.test.ts index 07b0f5120..05a428459 100644 --- a/lib/emails/__tests__/validateSendEmailBody.test.ts +++ b/lib/emails/__tests__/validateSendEmailBody.test.ts @@ -240,4 +240,48 @@ describe("validateSendEmailBody", () => { if ("error" in result) expect(result.error.status).toBe(401); }); }); + + // recoupable/app#1949 F2: a rejected send records why, so the rejection rate is diagnosable. + describe("rejection reason", () => { + it("names the disallowed recipients and the sending account", async () => { + mockAssertRecipientsAllowed.mockResolvedValue({ + allowed: false, + disallowed: ["stranger@example.com", "other@example.com"], + }); + const request = createRequest( + { to: ["stranger@example.com", "other@example.com"], text: "body" }, + { "x-api-key": "k" }, + ); + const result = await validateSendEmailBody(request); + expect(result).toMatchObject({ + reason: "recipient_not_allowed: stranger@example.com, other@example.com", + accountId: "account-123", + }); + }); + + it("names the failing field when the body is invalid", async () => { + const request = createRequest({ to: ["d@example.com"], html: " " }, { "x-api-key": "k" }); + const result = await validateSendEmailBody(request); + expect(result).toMatchObject({ + reason: "invalid_body: html: a non-empty html or text body is required", + }); + expect("accountId" in result && result.accountId).toBeFalsy(); + }); + + it("records the account when it has no email on file", async () => { + mockSelectAccountEmails.mockResolvedValue([]); + const request = createRequest({ text: "body" }, { "x-api-key": "k" }); + const result = await validateSendEmailBody(request); + expect(result).toMatchObject({ reason: "no_account_email", accountId: "account-123" }); + }); + + it("records the auth status when authentication fails", async () => { + mockValidateAuthContext.mockResolvedValue( + NextResponse.json({ status: "error", error: "Unauthorized" }, { status: 401 }), + ); + const request = createRequest({ to: ["d@example.com"], text: "body" }); + const result = await validateSendEmailBody(request); + expect(result).toMatchObject({ reason: "auth_failed: 401" }); + }); + }); }); diff --git a/lib/emails/logEmailAttempt.ts b/lib/emails/logEmailAttempt.ts index 14c13f0c3..f7ab49f39 100644 --- a/lib/emails/logEmailAttempt.ts +++ b/lib/emails/logEmailAttempt.ts @@ -9,6 +9,8 @@ export type EmailAttemptLog = { accountId?: string | null; chatId?: string | null; resendId?: string; + /** Why the send was rejected or failed: a short code, then detail. */ + reason?: string | null; }; /** @@ -28,6 +30,7 @@ export async function logEmailAttempt(attempt: EmailAttemptLog): Promise { status: attempt.status, resend_id: attempt.resendId ?? null, raw_body: attempt.rawBody, + reason: attempt.reason ?? null, }); if (error) { console.error("email_send_log insert failed:", error); diff --git a/lib/emails/sendEmailHandler.ts b/lib/emails/sendEmailHandler.ts index 6fcc3ab51..e89db5ad2 100644 --- a/lib/emails/sendEmailHandler.ts +++ b/lib/emails/sendEmailHandler.ts @@ -46,7 +46,12 @@ export async function sendEmailHandler(request: NextRequest): Promise & /** * Validation outcome. Always carries `rawBody` — the request body as received — * so the handler can record it in `email_send_log` on both the rejected and the - * accepted paths without re-reading the request. + * accepted paths without re-reading the request. A rejection also carries + * `reason` (a short code, then detail) and the account once auth has resolved + * it, so the rejection rate can be grouped by cause (recoupable/app#1949 F2). */ export type ValidateSendEmailResult = - | { rawBody: string; error: NextResponse } + | { rawBody: string; error: NextResponse; reason: string; accountId?: string } | { rawBody: string; data: ValidatedSendEmailRequest }; /** @@ -54,7 +56,7 @@ export type ValidateSendEmailResult = * `subject` is derived from the body when omitted. Always returns `rawBody`. * * @param request - The NextRequest object - * @returns `{ rawBody, error }` if validation/auth/recipients fail, else `{ rawBody, data }`. + * @returns `{ rawBody, error, reason }` if validation/auth/recipients fail, else `{ rawBody, data }`. */ export async function validateSendEmailBody( request: NextRequest, @@ -72,18 +74,20 @@ export async function validateSendEmailBody( const result = sendEmailBodySchema.safeParse(parsed); if (!result.success) { const firstError = result.error.issues[0]; + const field = firstError.path.join("."); return { rawBody, error: NextResponse.json( { status: "error", missing_fields: firstError.path, error: firstError.message }, { status: 400, headers: getCorsHeaders() }, ), + reason: `invalid_body: ${field ? `${field}: ` : ""}${firstError.message}`, }; } const authContext = await validateAuthContext(request, { accountId: result.data.account_id }); if (authContext instanceof NextResponse) { - return { rawBody, error: authContext }; + return { rawBody, error: authContext, reason: `auth_failed: ${authContext.status}` }; } let to = result.data.to ?? []; @@ -97,6 +101,8 @@ export async function validateSendEmailBody( { status: "error", error: "No email address found for the authenticated account." }, { status: 400, headers: getCorsHeaders() }, ), + reason: "no_account_email", + accountId: authContext.accountId, }; } } @@ -116,6 +122,8 @@ export async function validateSendEmailBody( }, { status: 403, headers: getCorsHeaders() }, ), + reason: `recipient_not_allowed: ${recipientCheck.disallowed.join(", ")}`, + accountId: authContext.accountId, }; } diff --git a/types/database.types.ts b/types/database.types.ts index df3cd0917..878c3d0b7 100644 --- a/types/database.types.ts +++ b/types/database.types.ts @@ -2480,6 +2480,7 @@ export type Database = { created_at: string; id: string; raw_body: string | null; + reason: string | null; resend_id: string | null; status: string; }; @@ -2489,6 +2490,7 @@ export type Database = { created_at?: string; id?: string; raw_body?: string | null; + reason?: string | null; resend_id?: string | null; status: string; }; @@ -2498,6 +2500,7 @@ export type Database = { created_at?: string; id?: string; raw_body?: string | null; + reason?: string | null; resend_id?: string | null; status?: string; }; From 630caa3bdd44ce74faac40afea478639d36938a0 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Fri, 6 Nov 2026 23:42:46 -0500 Subject: [PATCH 2/2] Omit reason from inserts that have none Successful sends now leave the reason key out of the insert, so they keep logging even if this deploys before email_send_log.reason exists. The sent rows matter: welcome, valuation and abandoned-checkout emails dedupe on them. Co-Authored-By: Claude Opus 5.5 --- lib/emails/__tests__/logEmailAttempt.test.ts | 6 ++++-- lib/emails/logEmailAttempt.ts | 4 +++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/lib/emails/__tests__/logEmailAttempt.test.ts b/lib/emails/__tests__/logEmailAttempt.test.ts index fcdc3095b..539d69cb9 100644 --- a/lib/emails/__tests__/logEmailAttempt.test.ts +++ b/lib/emails/__tests__/logEmailAttempt.test.ts @@ -45,9 +45,11 @@ describe("logEmailAttempt", () => { expect(row.account_id).toBe("acc-1"); }); - it("stores a null reason when none is given", async () => { + // Sends without a reason never touch the column, so they keep logging even if + // this code ships before the email_send_log.reason migration is applied. + it("leaves reason out of the insert when none is given", async () => { await logEmailAttempt({ rawBody: "{}", status: "sent" }); - expect(mockInsert.mock.calls[0][0].reason).toBeNull(); + expect(mockInsert.mock.calls[0][0]).not.toHaveProperty("reason"); }); it("stores the full raw body (no truncation)", async () => { diff --git a/lib/emails/logEmailAttempt.ts b/lib/emails/logEmailAttempt.ts index f7ab49f39..c7a564a12 100644 --- a/lib/emails/logEmailAttempt.ts +++ b/lib/emails/logEmailAttempt.ts @@ -30,7 +30,9 @@ export async function logEmailAttempt(attempt: EmailAttemptLog): Promise { status: attempt.status, resend_id: attempt.resendId ?? null, raw_body: attempt.rawBody, - reason: attempt.reason ?? null, + // Only rejected/failed sends carry a reason; omitting the key otherwise keeps + // ordinary sends logging if this ships before the column exists. + ...(attempt.reason ? { reason: attempt.reason } : {}), }); if (error) { console.error("email_send_log insert failed:", error);