From 032b868cf738005a0e3ddc9a541edcdd00d8970f Mon Sep 17 00:00:00 2001 From: Joan Planas <114454447+joanproductivo@users.noreply.github.com> Date: Sat, 24 Oct 2026 18:22:32 +0200 Subject: [PATCH 1/2] fix(webhooks): ignore opens SES marks as automated SES publishes an Open for every fetch of the tracking pixel, including the ones mail providers make on their own. Gmail's servers fetch it a second or two after delivery whether or not anyone reads the email, so almost every email to Gmail was counted as opened, segments on opens were wrong, and workflows waiting for an open resumed seconds after sending. SES marks every Open with `isBotEvent` ("Likely" / "Unlikely"). Measured against a Gmail inbox, Gmail's fetch was "Likely" every time and every real open was "Unlikely", including one a few seconds after delivery and Apple Mail's proxy. An Open marked "Likely" now writes nothing: no openedAt, no open count, no status change, no `email.open` event and no workflow. The reader's own open arrives later and counts as the first one. An Open without the mark still counts, as before. The log line of every counted open shows its isBotEvent mark. Refs #531 Co-Authored-By: Claude Opus 5.5 --- apps/api/src/controllers/Webhooks.ts | 23 +++++- .../__tests__/Webhooks.automaticOpen.test.ts | 25 ++++++ .../__tests__/Webhooks.sns.test.ts | 81 +++++++++++++++++++ 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 apps/api/src/controllers/__tests__/Webhooks.automaticOpen.test.ts diff --git a/apps/api/src/controllers/Webhooks.ts b/apps/api/src/controllers/Webhooks.ts index 9b861d76d..112b53967 100644 --- a/apps/api/src/controllers/Webhooks.ts +++ b/apps/api/src/controllers/Webhooks.ts @@ -71,6 +71,17 @@ export function nextStatus(current: EmailStatus, incoming?: EmailStatus): EmailS return incomingRank >= currentRank ? incoming : undefined; } +/** + * Whether SES judged an Open to be made by software rather than a person. Mail providers fetch + * the tracking pixel on their own -- Gmail's servers do it on delivery, whether or not anyone + * reads the email -- and SES marks those fetches `isBotEvent: "Likely"`. Measured, Gmail's own + * fetch was "Likely" and every real open was "Unlikely", including one seconds after delivery + * and Apple Mail's proxy. An Open without the mark counts, as every Open did before SES added it. + */ +export function isAutomaticOpen(open?: {isBotEvent?: unknown} | null): boolean { + return open?.isBotEvent === 'Likely'; +} + /** * Webhooks Controller * Handles incoming webhooks from external services (AWS SNS/SES) @@ -414,7 +425,17 @@ export class Webhooks { break; case 'Open': - signale.success(`[WEBHOOK] Open received for ${email.contact.email} from ${email.project.name}`); + // Counting an automatic fetch as an open would stamp openedAt, move segments and resume + // workflows waiting for a real one, so nothing is written for it + if (isAutomaticOpen(body.open)) { + signale.info(`[WEBHOOK] Automatic open ignored for ${email.contact.email} from ${email.project.name}`); + return res.status(200).json({success: true}); + } + // The mark is logged only when it is text, so an unexpected payload cannot make logging + // throw and lose an open that would have counted + signale.success( + `[WEBHOOK] Open received for ${email.contact.email} from ${email.project.name} (isBotEvent: ${typeof body.open?.isBotEvent === 'string' ? body.open.isBotEvent : 'none'})`, + ); // Only set openedAt on first open if (!email.openedAt) { updateData.openedAt = now; diff --git a/apps/api/src/controllers/__tests__/Webhooks.automaticOpen.test.ts b/apps/api/src/controllers/__tests__/Webhooks.automaticOpen.test.ts new file mode 100644 index 000000000..ebdbb9809 --- /dev/null +++ b/apps/api/src/controllers/__tests__/Webhooks.automaticOpen.test.ts @@ -0,0 +1,25 @@ +import {describe, expect, it} from 'vitest'; +import {isAutomaticOpen} from '../Webhooks'; + +/** + * SES marks each Open with `isBotEvent`. Only an exact "Likely" leaves an open out: anything SES + * does not mark that way counts, as every open did before the mark existed. + */ +describe('isAutomaticOpen', () => { + it('leaves out an open SES marks as likely automated', () => { + expect(isAutomaticOpen({isBotEvent: 'Likely'})).toBe(true); + }); + + it('counts an open SES marks as made by a person', () => { + expect(isAutomaticOpen({isBotEvent: 'Unlikely'})).toBe(false); + }); + + it('counts an open without the mark, or with one it does not recognise', () => { + expect(isAutomaticOpen(undefined)).toBe(false); + expect(isAutomaticOpen(null)).toBe(false); + expect(isAutomaticOpen({})).toBe(false); + for (const isBotEvent of ['likely', 'Unknown', true, null]) { + expect(isAutomaticOpen({isBotEvent})).toBe(false); + } + }); +}); diff --git a/apps/api/src/controllers/__tests__/Webhooks.sns.test.ts b/apps/api/src/controllers/__tests__/Webhooks.sns.test.ts index 0f82c48e3..380556a3c 100644 --- a/apps/api/src/controllers/__tests__/Webhooks.sns.test.ts +++ b/apps/api/src/controllers/__tests__/Webhooks.sns.test.ts @@ -470,4 +470,85 @@ describe('Webhooks - SES event notifications', () => { expect(enforce).not.toHaveBeenCalled(); }); }); + + /** + * Mail providers fetch the tracking pixel on their own, and SES marks those fetches. These are + * the fetches measured against a Gmail inbox: Gmail's servers took the pixel about two seconds + * after sending ("Likely"), and the reader's open came later through Google's image proxy, or + * Apple's when reading in Apple Mail ("Unlikely"). + */ + describe('automatic opens', () => { + const AUTOMATIC = { + isBotEvent: 'Likely', + userAgent: + 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0', + }; + const PEOPLE = { + 'Gmail web': { + isBotEvent: 'Unlikely', + userAgent: 'Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)', + }, + 'Apple Mail': {isBotEvent: 'Unlikely', userAgent: 'Mozilla/5.0'}, + }; + const HUMAN = PEOPLE['Gmail web']; + + const open = (messageId: string, mark: typeof AUTOMATIC) => + notification('Open', messageId, {open: {...mark, timestamp: new Date().toISOString()}}); + + it('writes nothing for an open SES marks as automated', async () => { + const campaign = await factories.createCampaign({projectId, name: 'Gmail', status: 'SENT'}); + const email = await sentEmail('ses-automatic-1', campaign.id); + + const captured = await post(open('ses-automatic-1', AUTOMATIC)); + expect(captured.status).toBe(200); + + const updated = await prisma.email.findUnique({where: {id: email.id}}); + expect(updated?.status).toBe(EmailStatus.SENT); + expect(updated?.openedAt).toBeNull(); + expect(updated?.opens).toBe(0); + expect(await prisma.event.findFirst({where: {emailId: email.id, name: 'email.open'}})).toBeNull(); + expect(await CampaignService.sweepDirtyStats(100)).toBe(0); + }); + + it.each(Object.entries(PEOPLE))('counts an open SES marks as made by a person (%s)', async (client, mark) => { + const messageId = `ses-human-${client.replace(' ', '-')}`; + const email = await sentEmail(messageId); + + await post(open(messageId, mark)); + + const updated = await prisma.email.findUnique({where: {id: email.id}}); + expect(updated?.status).toBe(EmailStatus.OPENED); + expect(updated?.openedAt).not.toBeNull(); + expect(updated?.opens).toBe(1); + const events = await prisma.event.findMany({where: {emailId: email.id, name: 'email.open'}}); + expect(events).toHaveLength(1); + expect((events[0]?.data as {isFirstOpen?: boolean} | null)?.isFirstOpen).toBe(true); + }); + + it("counts the reader's open after the automatic fetch as the first one", async () => { + const email = await sentEmail('ses-automatic-2'); + + await post(open('ses-automatic-2', AUTOMATIC)); + await post(open('ses-automatic-2', HUMAN)); + + const updated = await prisma.email.findUnique({where: {id: email.id}}); + expect(updated?.opens).toBe(1); + const events = await prisma.event.findMany({where: {emailId: email.id, name: 'email.open'}}); + expect(events).toHaveLength(1); + expect((events[0]?.data as {isFirstOpen?: boolean} | null)?.isFirstOpen).toBe(true); + }); + + it('ignores a redelivered automatic open as well', async () => { + const email = await sentEmail('ses-automatic-3'); + + await post(open('ses-automatic-3', AUTOMATIC)); + await post(open('ses-automatic-3', AUTOMATIC)); + + const updated = await prisma.email.findUnique({where: {id: email.id}}); + expect(updated?.status).toBe(EmailStatus.SENT); + expect(updated?.openedAt).toBeNull(); + expect(updated?.opens).toBe(0); + expect(await prisma.event.count({where: {emailId: email.id, name: 'email.open'}})).toBe(0); + }); + }); }); From 9805c188ec4e9ffc44918cb1052dc0c754b74796 Mon Sep 17 00:00:00 2001 From: Joan Planas <114454447+joanproductivo@users.noreply.github.com> Date: Sat, 24 Oct 2026 18:22:32 +0200 Subject: [PATCH 2/2] docs(tracking): explain how automatic opens are left out Describe how Plunk treats the opens mail providers make on their own: Gmail can fetch the pixel on delivery, SES marks those fetches, and they are not counted. Corporate gateways that pre-fetch images are still counted unless SES marks them. The webhook event table said `email.open` and `email.click` fire the first time only; they fire on every open and click. Refs #531 Co-Authored-By: Claude Opus 5.5 --- apps/wiki/content/docs/guides/tracking.mdx | 3 ++- apps/wiki/content/docs/guides/webhooks.mdx | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/apps/wiki/content/docs/guides/tracking.mdx b/apps/wiki/content/docs/guides/tracking.mdx index a54b0d5f7..78a3cc7b4 100644 --- a/apps/wiki/content/docs/guides/tracking.mdx +++ b/apps/wiki/content/docs/guides/tracking.mdx @@ -13,7 +13,8 @@ When open tracking is enabled, Plunk includes a small invisible tracking pixel a ### Considerations - Open tracking depends on the mail client loading remote images. If a contact has images disabled, no open is recorded. -- Some clients (and corporate mail security gateways) pre-fetch images, which can produce false positive opens. +- Gmail can fetch the tracking pixel as soon as an email is delivered, whether or not anyone reads it. SES marks fetches like this as likely automated (`isBotEvent`), and Plunk does not count them: the open is recorded when the contact actually opens the email. +- Some other clients and corporate mail security gateways pre-fetch images too. Those opens are counted unless SES marks them as automated. - Apple Mail Privacy Protection masks individual opens — opens from Apple Mail are recorded but reflect proxy fetches rather than human reads. ## Click tracking diff --git a/apps/wiki/content/docs/guides/webhooks.mdx b/apps/wiki/content/docs/guides/webhooks.mdx index 853cf0500..973ae8c02 100644 --- a/apps/wiki/content/docs/guides/webhooks.mdx +++ b/apps/wiki/content/docs/guides/webhooks.mdx @@ -29,8 +29,8 @@ Plunk automatically tracks a set of internal events that you can use as workflow | ----------------- | -------------------------------------------------------------------------------------------------------- | | `email.sent` | An email was successfully sent | | `email.delivery` | An email was delivered to the recipient | -| `email.open` | A contact opened an email for the first time | -| `email.click` | A contact clicked a link in an email for the first time | +| `email.open` | A contact opened an email. Opens SES marks as automated are left out | +| `email.click` | A contact clicked a link in an email | | `email.bounce` | An email bounced (hard or soft bounce) | | `email.complaint` | A contact marked an email as spam | | `email.received` | An email was received at your verified domain (requires [inbound email setup](/guides/receiving-emails)) |