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); + }); + }); }); 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)) |