Skip to content

Commit 449174b

Browse files
Rajatclaude
andcommitted
fix(api): pause the send on a permanent render error instead of dropping recipients
Counting render failures per recipient meant a team-wide problem (an empty mailing address, or a footer render bug like #154) unenrolled every recipient within minutes. Content and footer errors (EmailRenderError, TemplateValidationError, Liquid syntax errors) now auto-pause the broadcast or sequence with a new `render_error` reason: the team is notified, everyone stays queued, and resuming sends to all of them. Other errors while rendering are transient and are retried without counting. The send-failure path is back to exactly what it was on main. The pause banner and the owner email explain the reason in words, and SequenceReport.autoPause.reason in @sendlit/email-blocks gains `render_error`. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent b9580ed commit 449174b

7 files changed

Lines changed: 208 additions & 138 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@sendlit/email-blocks": patch
3+
---
4+
5+
`SequenceReport.autoPause.reason` can now be `render_error`: SendLit paused a broadcast or sequence because its email couldn't be built (for example the managed footer or the mailing address), keeping its recipients queued until it is resumed.

‎apps/api/src/automation/process-ongoing-sequence.test.ts‎

Lines changed: 10 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,9 @@ const { default: webViewRoutes } = await import("../tracking/web-view");
3535
const { requestApp } = await import("../test/http");
3636
const express = (await import("express")).default;
3737
const { getUnsubLink } = await import("../utils/mail");
38-
const { EmailRenderError, MissingTemplateVariablesError } = await import(
39-
"../mail/render"
38+
const { getNextPublishedEmail, processOngoingSequence } = await import(
39+
"./process-ongoing-sequence"
4040
);
41-
const { TemplateValidationError } = await import("../templates/validation");
42-
const { getNextPublishedEmail, isPermanentRenderError, processOngoingSequence } =
43-
await import("./process-ongoing-sequence");
4441

4542
const tdb = db as unknown as TestDb;
4643
const mockedSendMail = sendMail as unknown as Mock<typeof sendMail>;
@@ -185,7 +182,7 @@ describe("processOngoingSequence", () => {
185182
expect(outbound.providerMessageId).toBe("0100018f-ses-id-000000");
186183
});
187184

188-
it("rejects corrupted marketing content without a final managed footer before transport", async () => {
185+
it("pauses on corrupted marketing content without a final managed footer, before transport", async () => {
189186
const { team, contact } = await seedTeamAndContact(tdb);
190187
const { sequenceRow, emailRows } = await seedSequence(tdb, {
191188
teamId: team.id,
@@ -212,71 +209,18 @@ describe("processOngoingSequence", () => {
212209
contactId: contact.id,
213210
});
214211

215-
await expect(processOngoingSequence(row.id)).rejects.toThrow("footer_required");
212+
await processOngoingSequence(row.id);
216213
expect(mockedSendMail).not.toHaveBeenCalled();
217214
expect(await tdb.select().from(emailDeliveries)).toHaveLength(0);
218-
});
219-
220-
it("only counts content and footer render errors toward the bounce limit", () => {
221-
expect(isPermanentRenderError(new EmailRenderError("footer_render_failed"))).toBe(
222-
true,
223-
);
224-
expect(isPermanentRenderError(new TemplateValidationError("footer_required"))).toBe(
225-
true,
226-
);
227-
expect(isPermanentRenderError(new MissingTemplateVariablesError(["name"]))).toBe(
228-
true,
229-
);
230-
// A database blip or timeout while rendering must stay retryable.
231-
expect(
232-
isPermanentRenderError(new Error("Connection terminated unexpectedly")),
233-
).toBe(false);
234-
});
235-
236-
it("counts a render failure toward the bounce limit instead of retrying forever", async () => {
237-
const { team, contact } = await seedTeamAndContact(tdb);
238-
const { sequenceRow, emailRows } = await seedSequence(tdb, {
239-
teamId: team.id,
240-
emails: [{ emailId: "email_e1", subject: "Broken" }],
241-
});
242-
await tdb
243-
.update(sequenceEmails)
244-
.set({
245-
content: {
246-
style: {},
247-
meta: {},
248-
content: [{ blockType: "text", settings: { content: "No footer" } }],
249-
},
250-
})
251-
.where(eq(sequenceEmails.id, emailRows[0].id));
252-
const row = await seedOngoingSequence(tdb, {
253-
teamId: team.id,
254-
sequenceId: sequenceRow.id,
255-
contactId: contact.id,
256-
});
257-
258-
await expect(processOngoingSequence(row.id)).rejects.toThrow("footer_required");
259-
const [after] = await tdb
260-
.select()
261-
.from(ongoingSequences)
262-
.where(eq(ongoingSequences.id, row.id));
263-
expect(after.retryCount).toBe(1);
264-
265-
// sequenceBounceLimit defaults to 3: two more failures drop the row.
266-
await tdb
267-
.update(ongoingSequences)
268-
.set({ retryCount: 2 })
269-
.where(eq(ongoingSequences.id, row.id));
270-
await expect(processOngoingSequence(row.id)).rejects.toThrow("footer_required");
271-
expect(
272-
await tdb.select().from(ongoingSequences).where(eq(ongoingSequences.id, row.id)),
273-
).toHaveLength(0);
274-
const [seqAfter] = await tdb
215+
const [paused] = await tdb
275216
.select()
276217
.from(sequences)
277218
.where(eq(sequences.id, sequenceRow.id));
278-
expect((seqAfter.report as any).sequence.failed).toContain(contact.contactId);
279-
expect(mockedSendMail).not.toHaveBeenCalled();
219+
expect(paused.status).toBe("paused");
220+
expect((paused.report as any).autoPause).toMatchObject({
221+
reason: "render_error",
222+
error: "footer_required",
223+
});
280224
});
281225

282226
it("skips a suppressed recipient without sending or recording a delivery", async () => {

‎apps/api/src/automation/process-ongoing-sequence.ts‎

Lines changed: 53 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { eq } from "drizzle-orm";
2+
import { LiquidError } from "liquidjs";
23
import { recordPacedSend } from "../abuse/telemetry";
34
import { commitSendReservation, releaseSendReservation } from "../billing/entitlements";
45
import { sequenceBounceLimit } from "../config/constants";
@@ -24,7 +25,7 @@ import {
2425
} from "../delivery-feedback/outbound-send";
2526
import { isRecipientSuppressed } from "../delivery-feedback/suppression-queries";
2627
import { renderCampaignHtml } from "../mail/campaign";
27-
import { EmailRenderError, MissingTemplateVariablesError } from "../mail/render";
28+
import { EmailRenderError } from "../mail/render";
2829
import { quotaExhaustionDeferral, SendDeferredError } from "../mail/rate-limit";
2930
import { sendMail } from "../mail/send";
3031
import { captureError, captureEvent } from "../observability";
@@ -296,12 +297,25 @@ async function attemptMailSending({
296297
publication: sequence.type === "broadcast" ? sequence : null,
297298
});
298299
} catch (err: any) {
299-
// A content or footer-settings failure repeats on every retry until the
300-
// content or settings change, so count it like any other failed attempt
301-
// and let it stop instead of retrying forever. Anything else (a database
302-
// blip while rendering) is transient: retry without using up the limit.
300+
logger.error(
301+
{
302+
error: err.message,
303+
sequence_id: sequence.sequenceId,
304+
contactId: contact.contactId,
305+
},
306+
"attemptMailSending render failed",
307+
);
308+
// Content or footer-settings problems fail the same way for every
309+
// recipient until the team fixes them, so retrying can't help and
310+
// dropping recipients would lose them. Pause the whole send instead: the
311+
// team is notified and everyone stays queued for when it is resumed. Any
312+
// other error (a database blip while rendering) is transient and is
313+
// simply retried.
303314
if (isPermanentRenderError(err)) {
304-
await recordFailedAttempt({ sequence, contact, ongoingSequence });
315+
await autoPauseSequence(sequence, "render_error", {
316+
error: String(err?.message ?? err).slice(0, 300),
317+
});
318+
throw new SequencePausedError();
305319
}
306320
throw err;
307321
}
@@ -416,12 +430,36 @@ async function attemptMailSending({
416430
});
417431
throw new SequencePausedError();
418432
}
419-
await recordFailedAttempt({
420-
sequence,
421-
contact,
422-
ongoingSequence,
423-
outboundId: outboundForReservation?.id,
424-
});
433+
const retryCount = ongoingSequence.retryCount + 1;
434+
if (retryCount >= sequenceBounceLimit) {
435+
if (outboundForReservation) {
436+
await releaseSendReservation(outboundForReservation.id).catch(() => undefined);
437+
}
438+
await db
439+
.update(sequences)
440+
.set({
441+
report: {
442+
...(sequence.report as any),
443+
sequence: {
444+
...(sequence.report as any)?.sequence,
445+
failed: [
446+
...((sequence.report as any)?.sequence?.failed || []),
447+
contact.contactId,
448+
],
449+
},
450+
},
451+
})
452+
.where(eq(sequences.id, sequence.id));
453+
await deleteOngoingSequence(ongoingSequence.id);
454+
} else {
455+
// Keep the reservation through a transient retry. It expires and
456+
// is reopened atomically by reserveSend, preventing a retry from
457+
// bypassing the monthly quota.
458+
await db
459+
.update(ongoingSequences)
460+
.set({ retryCount })
461+
.where(eq(ongoingSequences.id, ongoingSequence.id));
462+
}
425463
logger.error(
426464
{
427465
error: err.message,
@@ -434,60 +472,16 @@ async function attemptMailSending({
434472
}
435473
}
436474

475+
/** Whether a render error comes from the email's content or the team's footer
476+
* settings, and so repeats for every recipient until the team changes them. */
437477
export function isPermanentRenderError(err: unknown): boolean {
438478
return (
439479
err instanceof EmailRenderError ||
440480
err instanceof TemplateValidationError ||
441-
err instanceof MissingTemplateVariablesError
481+
err instanceof LiquidError
442482
);
443483
}
444484

445-
/** Counts one failed attempt for this recipient. At `sequenceBounceLimit` the
446-
* recipient is recorded as failed and dropped; before that the row stays due
447-
* for another try. */
448-
async function recordFailedAttempt({
449-
sequence,
450-
contact,
451-
ongoingSequence,
452-
outboundId,
453-
}: {
454-
sequence: typeof sequences.$inferSelect;
455-
contact: NonNullable<Awaited<ReturnType<typeof getContactById>>>;
456-
ongoingSequence: OngoingSequenceRow;
457-
outboundId?: string;
458-
}) {
459-
const retryCount = ongoingSequence.retryCount + 1;
460-
if (retryCount >= sequenceBounceLimit) {
461-
if (outboundId) {
462-
await releaseSendReservation(outboundId).catch(() => undefined);
463-
}
464-
await db
465-
.update(sequences)
466-
.set({
467-
report: {
468-
...(sequence.report as any),
469-
sequence: {
470-
...(sequence.report as any)?.sequence,
471-
failed: [
472-
...((sequence.report as any)?.sequence?.failed || []),
473-
contact.contactId,
474-
],
475-
},
476-
},
477-
})
478-
.where(eq(sequences.id, sequence.id));
479-
await deleteOngoingSequence(ongoingSequence.id);
480-
} else {
481-
// Keep the reservation through a transient retry. It expires and
482-
// is reopened atomically by reserveSend, preventing a retry from
483-
// bypassing the monthly quota.
484-
await db
485-
.update(ongoingSequences)
486-
.set({ retryCount })
487-
.where(eq(ongoingSequences.id, ongoingSequence.id));
488-
}
489-
}
490-
491485
/** Applies the email's on-send action (`tag:add` / `tag:remove`). The mail is
492486
* already delivered at this point, so a failure here is logged but never
493487
* bubbles up — otherwise the retry loop would send the email again. */

‎apps/api/src/automation/sending-health.test.ts‎

Lines changed: 92 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ import {
66
it,
77
type Mock,
88
mock,
9+
spyOn,
910
vi,
1011
} from "bun:test";
1112
import { eq } from "drizzle-orm";
13+
import { Liquid } from "liquidjs";
1214

1315
mock.module("../db/client", async () => {
1416
const { makeTestDb } = await import("../test/db.js");
@@ -24,11 +26,15 @@ const { sendMail } = await import("../mail/send");
2426
const { seedTeamAndContact, truncateAll } = await import("../test/db");
2527
type TestDb = import("../test/db").TestDb;
2628
const { seedOngoingSequence, seedSequence } = await import("../test/fixtures");
27-
const { processOngoingSequence } = await import("./process-ongoing-sequence");
28-
const { getDueOngoingSequences } = await import("./queries");
29-
const { resetSendingHealthCacheForTests, isFatalEspError } = await import(
30-
"./sending-health"
29+
const { isPermanentRenderError, processOngoingSequence } = await import(
30+
"./process-ongoing-sequence"
3131
);
32+
const { EmailRenderError } = await import("../mail/render");
33+
const { TemplateValidationError } = await import("../templates/validation");
34+
const generalSettings = await import("../settings/general/queries");
35+
const { getDueOngoingSequences } = await import("./queries");
36+
const { resetSendingHealthCacheForTests, isFatalEspError, renderErrorReason } =
37+
await import("./sending-health");
3238
const { startSequence } = await import("../sequences/queries");
3339

3440
const tdb = db as unknown as TestDb;
@@ -126,6 +132,88 @@ describe("auto-pause (#25)", () => {
126132
expect(isFatalEspError(new Error("454 Throttling failure"))).toBe(false);
127133
});
128134

135+
it("pauses on a footer settings error and keeps every recipient queued until resumed", async () => {
136+
const { team, sequenceRow, rows } = await broadcastTo(2);
137+
// A team-wide problem: every recipient's footer fails the same way.
138+
await tdb
139+
.update(schema.settings)
140+
.set({ mailingAddress: "" })
141+
.where(eq(schema.settings.teamId, team.id));
142+
143+
await processOngoingSequence(rows[0].id);
144+
145+
expect(mockedSendMail).not.toHaveBeenCalled();
146+
const paused = await sequenceById(sequenceRow.id);
147+
expect(paused.status).toBe("paused");
148+
expect((paused.report as any).autoPause).toMatchObject({
149+
reason: "render_error",
150+
error: "footer_render_context_required",
151+
});
152+
// Nobody is dropped or charged a retry, and nothing is polled while paused.
153+
const queued = await tdb.select().from(schema.ongoingSequences);
154+
expect(queued).toHaveLength(2);
155+
expect(
156+
queued.every((row) => row.retryCount === 0 && !row.processingStartedAt),
157+
).toBe(true);
158+
expect(await getDueOngoingSequences()).toEqual([]);
159+
160+
// Fixed and resumed: everyone gets the email and the broadcast completes.
161+
await tdb
162+
.update(schema.settings)
163+
.set({ mailingAddress: "1 Test St, Testville" })
164+
.where(eq(schema.settings.teamId, team.id));
165+
await startSequence({ teamId: team.id, sequenceId: sequenceRow.sequenceId });
166+
for (const row of rows) await processOngoingSequence(row.id);
167+
expect(mockedSendMail).toHaveBeenCalledTimes(2);
168+
expect((await sequenceById(sequenceRow.id)).status).toBe("completed");
169+
});
170+
171+
it("retries a transient error while rendering without pausing or counting it", async () => {
172+
const { sequenceRow, rows } = await broadcastTo(1);
173+
const spy = spyOn(generalSettings, "getTeamSettingsRow").mockRejectedValueOnce(
174+
new Error("Connection terminated unexpectedly"),
175+
);
176+
try {
177+
await expect(processOngoingSequence(rows[0].id)).rejects.toThrow(
178+
"Connection terminated unexpectedly",
179+
);
180+
} finally {
181+
spy.mockRestore();
182+
}
183+
184+
expect((await sequenceById(sequenceRow.id)).status).toBe("active");
185+
const [row] = await tdb.select().from(schema.ongoingSequences);
186+
expect(row.retryCount).toBe(0);
187+
expect(row.processingStartedAt).toBeNull();
188+
// Recovered: the next attempt sends normally.
189+
await processOngoingSequence(rows[0].id);
190+
expect(mockedSendMail).toHaveBeenCalledTimes(1);
191+
});
192+
193+
it("treats only content and footer errors as permanent render errors", () => {
194+
expect(isPermanentRenderError(new EmailRenderError("footer_render_failed"))).toBe(
195+
true,
196+
);
197+
expect(isPermanentRenderError(new TemplateValidationError("footer_required"))).toBe(
198+
true,
199+
);
200+
let liquidSyntaxError: unknown;
201+
try {
202+
new Liquid().parse("{{ name");
203+
} catch (err) {
204+
liquidSyntaxError = err;
205+
}
206+
expect(isPermanentRenderError(liquidSyntaxError)).toBe(true);
207+
expect(
208+
isPermanentRenderError(new Error("Connection terminated unexpectedly")),
209+
).toBe(false);
210+
expect(renderErrorReason("footer_render_context_required")).toContain(
211+
"no mailing address",
212+
);
213+
expect(renderErrorReason("footer_render_failed")).toContain("footer");
214+
expect(renderErrorReason("footer_required")).toContain("footer");
215+
});
216+
129217
it("resumes a paused broadcast's queued deliveries without running its audience again", async () => {
130218
process.env.AUTO_PAUSE_MIN_SENT = "1";
131219
const { team, sequenceRow, rows } = await broadcastTo(2);

0 commit comments

Comments
 (0)