Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion apps/api/src/controllers/Webhooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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;
Expand Down
25 changes: 25 additions & 0 deletions apps/api/src/controllers/__tests__/Webhooks.automaticOpen.test.ts
Original file line number Diff line number Diff line change
@@ -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);
}
});
});
81 changes: 81 additions & 0 deletions apps/api/src/controllers/__tests__/Webhooks.sns.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
});
});
});
3 changes: 2 additions & 1 deletion apps/wiki/content/docs/guides/tracking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions apps/wiki/content/docs/guides/webhooks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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)) |
Expand Down
Loading