Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

127 KB
Raw Blame
import { mockFetch } from '~/tests/helpers/mocks/request.mock'

import { MessageRejected, SendingPausedException, TooManyRequestsException } from '@aws-sdk/client-sesv2'
import { DateTime } from 'luxon'
import { Pool } from 'pg'
import { register } from 'prom-client'

import { FixtureHogFlowBuilder } from '~/cdp/_tests/builders/hogflow.builder'
import { createExampleInvocation, insertIntegration } from '~/cdp/_tests/fixtures'
import { EmailStatusOutput } from '~/cdp/outputs/outputs'
import {
    CyclotronInvocationQueueParametersEmailSchema,
    CyclotronInvocationQueueParametersEmailType,
} from '~/cdp/schema/cyclotron'
import { TRANSACTIONAL_EMAIL_EVENT } from '~/cdp/services/hogflows/hogflow-sensitivity'
import { attachmentMetadata, decodeAttachments } from '~/cdp/services/hogflows/transactional-email'
import { CyclotronJobInvocationHogFunction } from '~/cdp/types'
import { IngestionOutputs } from '~/common/outputs/ingestion-outputs'
import { createRedisV2PoolFromConfig } from '~/common/redis/redis-v2'
import { closeHub, createHub } from '~/common/utils/db/hub'
import { PostgresUse } from '~/common/utils/db/postgres'
import { parseJSON } from '~/common/utils/json-parse'
import { UUIDT } from '~/common/utils/utils'
import { waitForExpect } from '~/tests/helpers/expectations'
import { createTestTeamFixture } from '~/tests/helpers/sql'
import { INVALID_TEAM_ID_KEYS } from '~/tests/helpers/team'

import { Hub, Team } from '../../../types'
import { RecipientsManagerService } from '../managers/recipients-manager.service'
import { TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'
import { RateLimiterService } from '../rate-limiter/rate-limiter.service'
import { EmailAttachmentsService } from './email-attachments.service'
import { selectEmailSenderIntegrationId } from './email-sender-selection'
import { EmailStatusService } from './email-status.service'
import { EmailSuppressionService, emailSuppressionConfigFromEnv } from './email-suppression.service'
import {
    EmailService,
    formatMailbox,
    parseAddressList,
    parseTierCaps,
    sanitizeEmailSubject,
    teamEmailCapBucket,
} from './email.service'
import { MailDevAPI } from './helpers/maildev'
import { EmailTrackingCodeSigner } from './helpers/tracking-code'
import { MessageAssetsService } from './message-assets.service'
import { RecipientTokensService } from './recipient-tokens.service'

class ThrottlingException extends Error {
    constructor(message: string) {
        super(message)
        this.name = 'ThrottlingException'
    }
}

async function metricValue(name: string, labels: Record<string, string>, metricName = name): Promise<number> {
    const metric = await register.getSingleMetric(name)!.get()
    const values: { labels: Partial<Record<string, string | number>>; value: number; metricName?: string }[] =
        metric.values
    const sample = values.find(
        (value) =>
            (value.metricName ?? name) === metricName &&
            Object.entries(labels).every(([key, labelValue]) => value.labels[key] === labelValue)
    )
    return sample?.value ?? 0
}

describe('sanitizeEmailSubject', () => {
    it.each([
        ['passes through normal text', 'Hello World', 'Hello World'],
        ['strips null bytes', 'Hello\x00World', 'HelloWorld'],
        ['replaces newlines with space', 'Hello\r\nWorld', 'Hello World'],
        ['replaces lone CR with space', 'Hello\rWorld', 'Hello World'],
        ['replaces lone LF with space', 'Hello\nWorld', 'Hello World'],
        ['strips control chars (BEL, BS, ESC)', 'He\x07ll\x08o\x1BWorld', 'HelloWorld'],
        ['strips DEL character', 'Hello\x7FWorld', 'HelloWorld'],
        ['preserves horizontal tab', 'Hello\tWorld', 'Hello\tWorld'],
        ['trims leading/trailing whitespace', '  Hello World  ', 'Hello World'],
        [
            'collapses multiple newlines into single space',
            'Hello \\ \ goodbye rn\r\n\r\nn ¯\_(ツ)_/¯',
            'Hello \\  goodbye rn n ¯\_(ツ)_/¯',
        ],
        ['handles mixed control chars and newlines', '\x00Hello\r\n\x07World\x1B', 'Hello World'],
        ['preserves unicode characters', 'Héllo Wörld 🎉', 'Héllo Wörld 🎉'],
        ['preserves email-typical special chars', 'Re: Your order #1234 — 50% off!', 'Re: Your order #1234 — 50% off!'],
    ])('%s', (_name, input, expected) => {
        expect(sanitizeEmailSubject(input)).toEqual(expected)
    })
})

describe('formatMailbox', () => {
    it.each([
        ['no name', undefined, '[email protected]'],
        ['an empty name', '  ', '[email protected]'],
        ['a plain name', 'Dry Run', '"Dry Run" <[email protected]>'],
        ['an apostrophe and ampersand', "O'Brien & Co", `"O'Brien & Co" <[email protected]>`],
        ['a double quote', 'The "Real" Dry', '"The \\"Real\\" Dry" <[email protected]>'],
        ['a backslash', 'Dry\\Run', '"Dry\\\\Run" <[email protected]>'],
        [
            'a line break that would start a header',
            'Dry\r\nBcc: [email protected]',
            '"DryBcc: [email protected]" <[email protected]>',
        ],
        [
            'a non-ASCII name as an RFC 2047 encoded word',
            'Café Müller',
            '=?UTF-8?Q?Caf=C3=A9_M=C3=BCller?= <[email protected]>',
        ],
    ])('formats %s', (_name, name, expected) => {
        expect(formatMailbox(name, '[email protected]')).toEqual(expected)
    })

    it.each([
        ['CJK name with a character outside the emoji range', '株式会社山田商事部𠮷田'.repeat(4)],
        ['emoji name', 'Launch party 🎉🚀 '.repeat(5)],
    ])('keeps a long %s intact across encoded words', (_desc, name) => {
        const [displayName, address] = formatMailbox(name, '[email protected]').split(' <')
        const encodedWords = displayName.split(' ')

        expect(encodedWords.map(decodeEncodedWord).join('')).toEqual(name.trim())
        expect(address).toEqual('[email protected]>')
        expect(encodedWords.length).toBeGreaterThan(1)
        expect(Math.max(...encodedWords.map((word) => word.length))).toBeLessThanOrEqual(75)
    })
})

function decodeEncodedWord(word: string): string {
    const [, encoding, text] = word.match(/^=\?UTF-8\?([BQ])\?(.*)\?=$/i)!
    const bytes =
        encoding.toUpperCase() === 'B'
            ? Buffer.from(text, 'base64')
            : Buffer.from(
                  text
                      .replace(/_/g, ' ')
                      .replace(/=([0-9A-F]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16))),
                  'latin1'
              )
    return bytes.toString('utf8')
}

describe('parseAddressList', () => {
    it.each([
        ['clean input', '[email protected], [email protected]', ['[email protected]', '[email protected]']],
        ['extra spaces', '  [email protected] ,  [email protected]  ', ['[email protected]', '[email protected]']],
        ['trailing comma', '[email protected], [email protected],', ['[email protected]', '[email protected]']],
    ])('%s', (_name, input, expected) => {
        expect(parseAddressList(input)).toEqual(expected)
    })

    it('should return undefined for empty values', () => {
        expect(parseAddressList(undefined)).toBeUndefined()
        expect(parseAddressList('')).toBeUndefined()
        expect(parseAddressList(',')).toBeUndefined()
    })
})

let integrationIdBase: number

const getIntegrationId = (id: number): number => integrationIdBase + id

const createEmailParams = (
    params: Partial<CyclotronInvocationQueueParametersEmailType> = {}
): CyclotronInvocationQueueParametersEmailType => {
    const from = params.from ?? { integrationId: 1 }
    return {
        type: 'email',
        to: { email: '[email protected]', name: 'Test User' },
        subject: 'Test Subject',
        text: 'Test Text',
        html: 'Test HTML',
        ...params,
        from: {
            ...from,
            integrationId: getIntegrationId(from.integrationId),
            integrationIds: from.integrationIds?.map(getIntegrationId),
        },
    }
}
describe('EmailService', () => {
    let service: EmailService
    let hub: Hub
    let team: Team
    let workflowsActivationReporter: { report: jest.Mock }
    beforeEach(async () => {
        hub = await createHub({})
        team = (await createTestTeamFixture(hub.postgres)).team
        integrationIdBase = team.id
        workflowsActivationReporter = { report: jest.fn() }
        service = new EmailService(
            {
                sesAccessKeyId: hub.SES_ACCESS_KEY_ID,
                sesSecretAccessKey: hub.SES_SECRET_ACCESS_KEY,
                sesRegion: hub.SES_REGION,
                sesEndpoint: hub.SES_ENDPOINT,
                sesTrackedConfigurationSet: hub.SES_TRACKED_CONFIGURATION_SET,
                sesUntrackedConfigurationSet: hub.SES_UNTRACKED_CONFIGURATION_SET,
            },
            hub.integrationManager,
            new TeamWorkflowsConfigService(hub.postgres, hub.pubSub),
            hub.ENCRYPTION_SALT_KEYS,
            hub.SITE_URL,
            new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
            new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
            new RecipientsManagerService(hub.postgres),
            null,
            workflowsActivationReporter
        )
        mockFetch.mockClear()
    })
    afterEach(async () => {
        await closeHub(hub)
    })
    describe('when SES is not configured', () => {
        it('should not crash on construction and should fail explicitly on send', async () => {
            const serviceWithoutSES = new EmailService(
                {
                    sesAccessKeyId: '',
                    sesSecretAccessKey: '',
                    sesRegion: '',
                    sesEndpoint: '',
                    sesTrackedConfigurationSet: 'posthog-messaging',
                    sesUntrackedConfigurationSet: '',
                },
                hub.integrationManager,
                new TeamWorkflowsConfigService(hub.postgres, hub.pubSub),
                hub.ENCRYPTION_SALT_KEYS,
                hub.SITE_URL,
                new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
                new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
                new RecipientsManagerService(hub.postgres),
                null,
                { report: jest.fn() }
            )
            expect(serviceWithoutSES.sesV2Client).toBeNull()

            await insertIntegration(hub.postgres, team.id, {
                id: getIntegrationId(1),
                kind: 'email',
                config: {
                    email: '[email protected]',
                    name: 'Test User',
                    domain: 'posthog.com',
                    verified: true,
                    provider: 'ses',
                },
            })
            const invocation = createExampleInvocation({ team_id: team.id, id: 'function-1' })
            invocation.id = 'invocation-1'
            invocation.state.vmState = { stack: [] } as any
            invocation.queueParameters = createEmailParams({ from: { integrationId: 1 } })

            const result = await serviceWithoutSES.executeSendEmail(invocation)
            expect(result.error).toBe('SES is not configured - set SES_REGION and AWS credentials')
        })
    })

    describe('executeSendEmail', () => {
        let invocation: CyclotronJobInvocationHogFunction
        let sendEmailSpy: jest.SpyInstance
        beforeEach(async () => {
            await insertIntegration(hub.postgres, team.id, {
                id: getIntegrationId(1),
                kind: 'email',
                config: {
                    email: '[email protected]',
                    name: 'Test User',
                    domain: 'posthog.com',
                    verified: true,
                    provider: 'ses',
                },
            })
            invocation = createExampleInvocation({ team_id: team.id, id: 'function-1' })
            invocation.id = 'invocation-1'
            invocation.state.vmState = {
                stack: [],
            } as any
            invocation.queueParameters = createEmailParams({ from: { integrationId: 1 } })
            invocation.queueMetadata = { originQueue: 'hogflow', originPriority: 2 }

            // Mock SES v2 send to avoid actual AWS calls
            sendEmailSpy = jest.spyOn(service.sesV2Client!, 'send') as any
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
        })
        describe('integration validation', () => {
            beforeEach(async () => {
                await insertIntegration(hub.postgres, team.id, {
                    id: getIntegrationId(2),
                    kind: 'email',
                    config: {
                        email: '[email protected]',
                        name: 'Test User',
                        domain: 'other-domain.com',
                        verified: false,
                    },
                })
                await insertIntegration(hub.postgres, team.id, {
                    id: getIntegrationId(3),
                    kind: 'slack',
                    config: {},
                })
            })
            it('should validate if the integration is not found', async () => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 100 },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toMatchInlineSnapshot(
                    `"Email integration not found. The sender configured for this step no longer exists — select a new sender in the workflow's email step."`
                )
            })
            it('should validate if the integration is not an email integration', async () => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 3 },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toMatchInlineSnapshot(
                    `"The integration configured for this step is not an email channel — select an email sender in the workflow's email step."`
                )
            })
            it('should validate if the integration is not the correct team', async () => {
                invocation.teamId = 100
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toMatchInlineSnapshot(
                    `"Email integration not found. The sender configured for this step no longer exists — select a new sender in the workflow's email step."`
                )
            })
            it.each([
                ['a workflow send', true, false, 1],
                ['a workflow test send', true, true, 0],
                ['a hog function send', false, false, 0],
            ])(
                'should fail on an unverified email domain and report it only for a real workflow send: %s',
                async (_name, fromWorkflow, isTest, reports) => {
                    invocation.queueParameters = createEmailParams({
                        from: { integrationId: 2 },
                    })
                    const sentInvocation = fromWorkflow
                        ? { ...invocation, hogFlow: new FixtureHogFlowBuilder().withTeamId(team.id).build() }
                        : invocation
                    const result = await service.executeSendEmail(sentInvocation, isTest)
                    expect(result.error).toMatchInlineSnapshot(
                        `"The selected email integration domain is not verified"`
                    )
                    expect(workflowsActivationReporter.report.mock.calls).toEqual(
                        Array(reports).fill([
                            team.id,
                            'workflows send failed',
                            { reason: 'unverified_domain', channel: 'email', workflow_id: invocation.functionId },
                        ])
                    )
                }
            )
            it('should send identical from and feedback forwarding args', async () => {
                // This test is important for spam classification - feedback forwarding email MUST match from email
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                expect(sendEmailSpy).toHaveBeenCalled()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.FromEmailAddress).toBe('"Test User" <[email protected]>')
                expect(sentCommand.input.FeedbackForwardingEmailAddress).toBe('[email protected]')
            })
            it('should allow a valid email integration and domain', async () => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
            })

            it('uses and logs the sender selected for this workflow invocation', async () => {
                await insertIntegration(hub.postgres, team.id, {
                    id: getIntegrationId(4),
                    kind: 'email',
                    config: {
                        email: '[email protected]',
                        name: 'Second Sender',
                        domain: 'posthog.com',
                        verified: true,
                        provider: 'ses',
                    },
                })
                invocation.id = Array.from({ length: 10 }, (_, index) => `invocation-${index}`).find(
                    (id) =>
                        selectEmailSenderIntegrationId(id, {
                            integrationId: getIntegrationId(1),
                            integrationIds: [getIntegrationId(1), getIntegrationId(4)],
                        }) === getIntegrationId(4)
                )!
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1, integrationIds: [1, 4] },
                })

                const result = await service.executeSendEmail(invocation)

                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.FromEmailAddress).toBe('"Second Sender" <[email protected]>')
                expect(result.logs.map((log) => log.message)).toContain(
                    'Email sent to [email protected] from Second Sender <[email protected]>'
                )
            })
        })
        describe('from overrides', () => {
            const maxLengthEmail = `${'a'.repeat(242)}@posthog.com`

            it.each<[string, { email?: string; name?: string }, string, string]>([
                [
                    'address on the verified domain',
                    { email: '[email protected]' },
                    '"Test User" <[email protected]>',
                    '[email protected]',
                ],
                [
                    'address at the maximum length',
                    { email: maxLengthEmail },
                    `"Test User" <${maxLengthEmail}>`,
                    maxLengthEmail,
                ],
                [
                    'address with different domain casing',
                    { email: '[email protected]' },
                    '"Test User" <[email protected]>',
                    '[email protected]',
                ],
                ['name only', { name: 'Community Team' }, '"Community Team" <[email protected]>', '[email protected]'],
                [
                    'name and address',
                    { email: '[email protected]', name: 'Community Team' },
                    '"Community Team" <[email protected]>',
                    '[email protected]',
                ],
                [
                    'empty overrides fall back to the integration sender',
                    { email: '', name: '' },
                    '"Test User" <[email protected]>',
                    '[email protected]',
                ],
                [
                    'name with quotes, angle brackets and a line break kept inside the quoted name',
                    { name: '"Evil" <[email protected]>,\r\n Bcc:\\' },
                    '"\\"Evil\\" <[email protected]>, Bcc:\\\\" <[email protected]>',
                    '[email protected]',
                ],
                [
                    'non-ASCII name with quotes as an RFC 2047 encoded word',
                    { name: 'Café "Müller"' },
                    '=?UTF-8?Q?Caf=C3=A9_=22M=C3=BCller=22?= <[email protected]>',
                    '[email protected]',
                ],
            ])('applies the %s', async (_desc, fromOverride, expectedFrom, expectedFeedback) => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1, ...fromOverride },
                })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.FromEmailAddress).toBe(expectedFrom)
                expect(sentCommand.input.FeedbackForwardingEmailAddress).toBe(expectedFeedback)
            })

            it.each<[string, string, string?]>([
                ['an address on an unverified domain', '[email protected]'],
                ['an address on a subdomain of the verified domain', '[email protected]'],
                ['a list of addresses', '[email protected], [email protected]'],
                ['an RFC-822 formatted address', '"Name" <[email protected]>'],
                ['a value that is not an email address', 'not-an-email'],
                [
                    'an address longer than the maximum length',
                    `${'a'.repeat(243)}@posthog.com`,
                    '254 characters or fewer',
                ],
                ['an overlong value that is not an email address', 'a'.repeat(255), '254 characters or fewer'],
            ])('discards %s and sends from the integration sender', async (_desc, email, expectedWarning = email) => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1, email },
                })
                const result = await service.executeSendEmail(invocation)
                // Failing the send would break every step still carrying the placeholder address
                // an old sender picker wrote, so an unusable override degrades to the integration's
                // own sender. The unverified address must never reach the provider either way.
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.FromEmailAddress).toBe('"Test User" <[email protected]>')
                expect(result.logs.some((log) => log.level === 'warn' && log.message.includes(expectedWarning))).toBe(
                    true
                )
            })
        })
        describe('email sending', () => {
            it('should send an email', async () => {
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                expect(sendEmailSpy).toHaveBeenCalled()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input).toMatchObject({
                    FromEmailAddress: '"Test User" <[email protected]>',
                    FeedbackForwardingEmailAddress: '[email protected]',
                    Destination: {
                        ToAddresses: ['"Test User" <[email protected]>'],
                    },
                    Content: {
                        Simple: {
                            Subject: {
                                Data: 'Test Subject',
                            },
                            Body: {
                                Text: {
                                    Data: 'Test Text',
                                },
                            },
                        },
                    },
                })
            })
        })
        describe('SES throttle handling', () => {
            // SES throttle responses become reschedule-with-backoff rather than
            // permanent failures. The local Valkey bucket already gates dequeue;
            // this path is the safety net for when SES disagrees with our estimate.
            // Retryable: TooManyRequestsException (SES v2's rate-limit class) and
            // ThrottlingException (generic AWS SDK throttle name surfaced from
            // the transport layer). SendingPausedException is *not* retryable —
            // it signals a reputation/account-state issue that needs operator
            // attention, not a 500ms reschedule.
            const throttleCases: Array<[string, () => Error]> = [
                [
                    'TooManyRequestsException',
                    () => new TooManyRequestsException({ $metadata: {}, message: 'Too many requests' }),
                ],
                ['ThrottlingException', () => new ThrottlingException('Rate exceeded')],
            ]
            it.each(throttleCases)('reschedules instead of failing when SES returns %s', async (_name, makeError) => {
                sendEmailSpy.mockRejectedValueOnce(makeError())

                const before = Date.now()
                const result = await service.executeSendEmail(invocation)

                expect(result.error).toBeUndefined()
                expect(result.finished).toBe(false)
                expect(result.invocation.queueScheduledAt).toBeDefined()
                const scheduledMs = result.invocation.queueScheduledAt!.toMillis()
                // Jittered 500–1000ms retry: must land in the future but never further
                // than the upper bound + scheduler overhead.
                expect(scheduledMs).toBeGreaterThanOrEqual(before + 400)
                expect(scheduledMs).toBeLessThan(before + 2000)
                expect(result.invocation.queueParameters).toEqual(invocation.queueParameters)
                expect(result.invocation.queueMetadata).toEqual(invocation.queueMetadata)
                // No business metric emitted on throttle — the eventual retry
                // will produce email_sent.
                expect(result.metrics ?? []).toEqual([])
            })

            it('keeps the send priority class across a throttle reschedule', async () => {
                // A bulk send enters the email queue at priority 1. On an SES throttle the job is
                // rescheduled on the email queue, so its priority must stay 1 — resetting it to the
                // fast-lane value 0 would let throttled bulk bursts jump ahead of transactional sends,
                // which is exactly the traffic the fast lane exists to protect.
                invocation.queuePriority = 1
                sendEmailSpy.mockRejectedValueOnce(
                    new TooManyRequestsException({ $metadata: {}, message: 'Too many requests' })
                )

                const result = await service.executeSendEmail(invocation)

                expect(result.finished).toBe(false)
                expect(result.invocation.queueScheduledAt).toBeDefined()
                expect(result.invocation.queuePriority).toBe(1)
            })

            it('hard-fails (not retry) when SES returns SendingPausedException', async () => {
                // Reputation/account-state pause won't recover in 500ms; retrying
                // just burns reschedules. Hard-fail so the failure surfaces via
                // email_failed and an operator can investigate.
                sendEmailSpy.mockRejectedValueOnce(
                    new SendingPausedException({ $metadata: {}, message: 'Sending paused' })
                )

                const result = await service.executeSendEmail(invocation)

                expect(result.finished).toBe(true)
                expect(result.error).toMatch(/Failed to send email via SES: Sending paused/)
                expect(result.metrics).toEqual(
                    expect.arrayContaining([expect.objectContaining({ metric_name: 'email_failed' })])
                )
            })

            it.each<[string, () => Error, string]>([
                [
                    'TooManyRequestsException',
                    () => new TooManyRequestsException({ $metadata: {}, message: 'Too many requests' }),
                    'throttled',
                ],
                ['ThrottlingException', () => new ThrottlingException('Rate exceeded'), 'throttled'],
                [
                    'SendingPausedException',
                    () => new SendingPausedException({ $metadata: {}, message: 'Sending paused' }),
                    'SendingPausedException',
                ],
                ['an unknown error', () => new Error('connect ECONNRESET for [email protected]'), 'other'],
            ])('counts an SES send that fails with %s as %s', async (_name, makeError, expectedResult) => {
                const labels = { result: expectedResult }
                const before = await metricValue('cdp_ses_send_results_total', labels)
                sendEmailSpy.mockRejectedValueOnce(makeError())

                await service.executeSendEmail(invocation)

                expect(await metricValue('cdp_ses_send_results_total', labels)).toBe(before + 1)
            })

            it('still fails the job for non-throttle SES errors', async () => {
                sendEmailSpy.mockRejectedValueOnce(
                    new MessageRejected({ $metadata: {}, message: 'something else broke' })
                )

                const result = await service.executeSendEmail(invocation)

                expect(result.finished).toBe(true)
                expect(result.error).toMatch(/Failed to send email via SES: something else broke/)
                // Business metric should record the failure.
                expect(result.metrics).toEqual(
                    expect.arrayContaining([expect.objectContaining({ metric_name: 'email_failed' })])
                )
            })
        })

        describe('queue-to-send latency', () => {
            // The job was created a minute ago and rescheduled after a throttle, so it became due again 5 seconds ago.
            // Running the email step clones the invocation, which resets queueScheduledAt before the send.
            const transactionalSend = (): void => {
                invocation.state.globals.event.event = '$transactional_email'
                invocation.hogFunction.metadata = { message_category_type: 'transactional' }
            }

            it.each([
                ['workflow', 'bulk', 'false', 'its rescheduled time', (): void => {}, 5_000, 60_000],
                ['transactional_api', 'fast', 'false', 'its creation', transactionalSend, 60_000, Infinity],
                // Alerts leave out a wait that the team sending cap causes on purpose.
                [
                    'transactional_api',
                    'fast',
                    'true',
                    'its creation after a team cap delay',
                    (): void => {
                        transactionalSend()
                        invocation.queueMetadata = { teamCapped: true }
                    },
                    60_000,
                    Infinity,
                ],
            ])(
                'observes the wait of a retried %s send on the %s lane with team_capped=%s from %s',
                async (source, priorityClass, teamCapped, _from, setUp, minWaitMs, maxWaitMs) => {
                    setUp()
                    invocation.queue = 'email'
                    invocation.queueCreatedAt = DateTime.utc().minus({ seconds: 60 })
                    invocation.queueDueAt = DateTime.utc().minus({ seconds: 5 })
                    invocation.queueScheduledAt = undefined
                    const name = 'cdp_email_queue_to_send_ms'
                    const labels = { source, priority_class: priorityClass, team_capped: teamCapped }
                    const countBefore = await metricValue(name, labels, `${name}_count`)
                    const sumBefore = await metricValue(name, labels, `${name}_sum`)

                    await service.executeSendEmail(invocation)

                    expect(await metricValue(name, labels, `${name}_count`)).toBe(countBefore + 1)
                    const waitMs = (await metricValue(name, labels, `${name}_sum`)) - sumBefore
                    expect(waitMs).toBeGreaterThanOrEqual(minWaitMs)
                    expect(waitMs).toBeLessThan(maxWaitMs)
                }
            )
        })

        describe('workflow sending rate limit', () => {
            let claimOrReserve: jest.Mock
            let limitedService: EmailService
            let limitedSendSpy: jest.SpyInstance

            beforeEach(() => {
                claimOrReserve = jest.fn().mockResolvedValue({ granted: 1, retryAfterMs: null, reserved: false })
                limitedService = new EmailService(
                    {
                        sesAccessKeyId: hub.SES_ACCESS_KEY_ID,
                        sesSecretAccessKey: hub.SES_SECRET_ACCESS_KEY,
                        sesRegion: hub.SES_REGION,
                        sesEndpoint: hub.SES_ENDPOINT,
                        sesTrackedConfigurationSet: hub.SES_TRACKED_CONFIGURATION_SET,
                        sesUntrackedConfigurationSet: hub.SES_UNTRACKED_CONFIGURATION_SET,
                    },
                    hub.integrationManager,
                    new TeamWorkflowsConfigService(hub.postgres, hub.pubSub),
                    hub.ENCRYPTION_SALT_KEYS,
                    hub.SITE_URL,
                    new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
                    new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
                    new RecipientsManagerService(hub.postgres),
                    null,
                    { report: jest.fn() },
                    undefined,
                    { claimOrReserve } as unknown as RateLimiterService
                )
                limitedSendSpy = jest.spyOn(limitedService.sesV2Client!, 'send') as any
                limitedSendSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.hogFunction.metadata = {
                    email_sending_rate_limit: { count: 120, period: 'minute' },
                }
            })

            it.each([
                // A reserved slot means "your turn is at this exact time". Park on it as-is:
                // wake earlier and the token is not there yet, so the send gets denied again
                // and goes to the back of the line.
                ['exactly at the reserved slot', 5000, true, 5000, 5000],
                // Sub-second slots too: flooring them to 1s would push the wake off its
                // slot and collide it with the slot behind.
                ['exactly at a sub-second reserved slot', 500, true, 500, 500],
                // Past the horizon there are no slots left and everyone gets the same "come
                // back in an hour", so those wakes get spread out (1x-2x) instead.
                [
                    'with spread when re-contending at the horizon',
                    60 * 60 * 1000,
                    false,
                    60 * 60 * 1000,
                    2 * 60 * 60 * 1000,
                ],
                // No horizon at all (error-path denial) falls back to the clamped token
                // interval: 120/minute refills every 500ms, clamped to [1s, 2s] jittered.
                ['on the clamped token interval when the limiter could not reserve', null, false, 1000, 2000],
            ])('reschedules a denied send %s', async (_name, retryAfterMs, reserved, minDelayMs, maxDelayMs) => {
                claimOrReserve.mockResolvedValue({ granted: 0, retryAfterMs, reserved })

                const before = Date.now()
                const result = await limitedService.executeSendEmail(invocation)
                const after = Date.now()

                expect(limitedSendSpy).not.toHaveBeenCalled()
                expect(result.error).toBeUndefined()
                expect(result.finished).toBe(false)
                expect(result.invocation.queueScheduledAt).toBeDefined()
                // The reschedule must carry the email payload forward: without queueParameters the
                // retry has nothing to send and the throttled email is dropped rather than delayed.
                expect(result.invocation.queueParameters).toEqual(invocation.queueParameters)
                expect(result.invocation.queueMetadata).toEqual(invocation.queueMetadata)
                // Bracketed against both ends of the call, so the bounds hold the delay itself
                // and not the time the call took.
                const scheduledMs = result.invocation.queueScheduledAt!.toMillis()
                expect(scheduledMs).toBeGreaterThanOrEqual(before + minDelayMs)
                expect(scheduledMs).toBeLessThanOrEqual(after + maxDelayMs)
                // No business metric on a pacing delay — the eventual send produces email_sent.
                expect(result.metrics ?? []).toEqual([])
            })

            it('parks consecutive denials on their exact reserved slots', async () => {
                // At 30/minute the limiter hands out slots 2s apart. Each send has to wake at
                // its own slot, exactly. If one wake moves even a little earlier, its token is
                // not there yet and the send goes to the back of the line.
                invocation.hogFunction.metadata = { email_sending_rate_limit: { count: 30, period: 'minute' } }
                const slotMs = 2000

                for (let i = 1; i <= 3; i++) {
                    claimOrReserve.mockResolvedValue({ granted: 0, retryAfterMs: i * slotMs, reserved: true })

                    const before = Date.now()
                    const denied = await limitedService.executeSendEmail(invocation)
                    const after = Date.now()

                    expect(denied.finished).toBe(false)
                    const parkedAt = denied.invocation.queueScheduledAt!.toMillis()
                    expect(parkedAt).toBeGreaterThanOrEqual(before + i * slotMs)
                    expect(parkedAt).toBeLessThanOrEqual(after + i * slotMs)
                }
            })

            it('scatters a backlog that overflows the reservation horizon', async () => {
                // When the backlog is deeper than one hour of refill there are no slots left:
                // every remaining send gets "come back in an hour". If they all came back at
                // the same moment they would pile up at the front of the queue again, so their
                // wakes get spread out over the hour.
                claimOrReserve.mockResolvedValue({ granted: 0, retryAfterMs: 60 * 60 * 1000, reserved: false })

                const parkedAt: number[] = []
                for (let i = 0; i < 20; i++) {
                    const denied = await limitedService.executeSendEmail(invocation)
                    expect(denied.finished).toBe(false)
                    parkedAt.push(denied.invocation.queueScheduledAt!.toMillis())
                }

                // The wakes must cover a real part of the hour, not one narrow window:
                // 20 of them spread over an hour should easily span more than 10 minutes.
                const spreadMs = Math.max(...parkedAt) - Math.min(...parkedAt)
                expect(spreadMs).toBeGreaterThan(10 * 60 * 1000)
            })

            it('claims one token scoped to the workflow and sends when granted', async () => {
                const result = await limitedService.executeSendEmail(invocation)

                expect(claimOrReserve).toHaveBeenCalledWith(
                    {
                        key: `@posthog/workflow-email-rate/${team.id}/function-1`,
                        requested: 1,
                        // Burst capacity is ~1s of budget (not the count), so the first period can't
                        // send ~2x the limit and an idle-expired bucket can't re-burst.
                        capacity: 2,
                        refillPerSecond: 2,
                    },
                    60 * 60 * 1000
                )
                expect(result.finished).toBe(true)
                expect(limitedSendSpy).toHaveBeenCalled()
            })

            it.each([
                ['no rate limit is configured', (): void => void (invocation.hogFunction.metadata = {})],
                [
                    'the configured value is malformed',
                    (): void =>
                        void (invocation.hogFunction.metadata = { email_sending_rate_limit: { count: 'lots' } }),
                ],
            ])('does not consult the bucket when %s', async (_name, setup) => {
                setup()

                const result = await limitedService.executeSendEmail(invocation)

                expect(claimOrReserve).not.toHaveBeenCalled()
                expect(result.finished).toBe(true)
                expect(limitedSendSpy).toHaveBeenCalled()
            })

            it('skips the limit for test sends', async () => {
                claimOrReserve.mockResolvedValue({ granted: 0, retryAfterMs: 5000 })

                const result = await limitedService.executeSendEmail(invocation, true)

                expect(claimOrReserve).not.toHaveBeenCalled()
                expect(result.finished).toBe(true)
                expect(limitedSendSpy).toHaveBeenCalled()
            })
        })

        // A workflow over its sending limit must not crowd out anyone else: every denied
        // send parks on its own future slot instead of retrying every second, and a
        // workflow without a limit keeps sending right past the parked backlog.
        describe('a denied backlog cannot crowd out other sends', () => {
            it('spreads denied sends over distinct future slots and leaves unlimited workflows untouched', async () => {
                const redis = createRedisV2PoolFromConfig({
                    connection: hub.CDP_REDIS_HOST
                        ? {
                              url: hub.CDP_REDIS_HOST,
                              options: { port: hub.CDP_REDIS_PORT, password: hub.CDP_REDIS_PASSWORD },
                          }
                        : { url: hub.REDIS_URL },
                    poolMinSize: hub.REDIS_POOL_MIN_SIZE,
                    poolMaxSize: hub.REDIS_POOL_MAX_SIZE,
                })
                const realLimitedService = new EmailService(
                    {
                        sesAccessKeyId: hub.SES_ACCESS_KEY_ID,
                        sesSecretAccessKey: hub.SES_SECRET_ACCESS_KEY,
                        sesRegion: hub.SES_REGION,
                        sesEndpoint: hub.SES_ENDPOINT,
                        sesTrackedConfigurationSet: hub.SES_TRACKED_CONFIGURATION_SET,
                        sesUntrackedConfigurationSet: hub.SES_UNTRACKED_CONFIGURATION_SET,
                    },
                    hub.integrationManager,
                    new TeamWorkflowsConfigService(hub.postgres, hub.pubSub),
                    hub.ENCRYPTION_SALT_KEYS,
                    hub.SITE_URL,
                    new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
                    new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
                    new RecipientsManagerService(hub.postgres),
                    null,
                    { report: jest.fn() },
                    undefined,
                    new RateLimiterService(redis, { name: 'workflow-email-backlog-test' })
                )
                const realSendSpy = jest.spyOn(realLimitedService.sesV2Client!, 'send') as any
                realSendSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                // 6/minute: refill 0.1 tokens/s, burst capacity 1. Slow enough that the test's
                // own wall-clock time cannot refill a token between the denials below.
                invocation.hogFunction.metadata = { email_sending_rate_limit: { count: 6, period: 'minute' } }

                const first = await realLimitedService.executeSendEmail(invocation)
                expect(first.finished).toBe(true)

                const parkedAt: number[] = []
                for (let i = 0; i < 4; i++) {
                    const denied = await realLimitedService.executeSendEmail(invocation)
                    expect(denied.finished).toBe(false)
                    parkedAt.push(denied.invocation.queueScheduledAt!.toMillis())
                }

                // Each denial must hold its own slot, one token interval (10s) apart. If the
                // parks all landed in the same window, the gaps between them would be near
                // zero or negative and the backlog would wake as one herd.
                for (let i = 1; i < parkedAt.length; i++) {
                    const gapMs = parkedAt[i] - parkedAt[i - 1]
                    expect(gapMs).toBeGreaterThan(9_000)
                    expect(gapMs).toBeLessThan(11_000)
                }

                // A workflow without a limit on the same team sends immediately, regardless of
                // the backlog next to it.
                const other = createExampleInvocation({ team_id: team.id, id: 'function-b' })
                other.id = 'invocation-b'
                other.state.vmState = { stack: [] } as any
                other.queueParameters = createEmailParams({ from: { integrationId: 1 } })
                const otherResult = await realLimitedService.executeSendEmail(other)

                expect(otherResult.finished).toBe(true)
                expect(realSendSpy).toHaveBeenCalledTimes(2)
            })
        })

        describe('parseTierCaps', () => {
            it.each([
                ['a whole table', '50,200', [50, 200]],
                // A decimal cap would make a claim fractional, and the limiter floors its grant
                // while the caller compares against the unfloored request. The claim then charges
                // the bucket and reads back as a denial, which starves the team on every retry.
                ['a decimal cap', '50,2.5', []],
                ['a zero cap', '50,0', []],
                ['nonsense', 'fifty', []],
            ])('%s', (_name, value, expected) => {
                expect(parseTierCaps(value)).toEqual(expected)
            })
        })

        describe('team sending cap (enforce mode)', () => {
            let claimAllOrNothing: jest.Mock
            let claimUpTo: jest.Mock
            let cappedService: EmailService
            let cappedSendSpy: jest.SpyInstance

            beforeEach(() => {
                claimAllOrNothing = jest.fn()
                claimUpTo = jest.fn().mockResolvedValue(0)
                const configService = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)
                jest.spyOn(configService, 'getEmailSendingTier').mockResolvedValue(0)
                cappedService = new EmailService(
                    {
                        sesAccessKeyId: hub.SES_ACCESS_KEY_ID,
                        sesSecretAccessKey: hub.SES_SECRET_ACCESS_KEY,
                        sesRegion: hub.SES_REGION,
                        sesEndpoint: hub.SES_ENDPOINT,
                        sesTrackedConfigurationSet: hub.SES_TRACKED_CONFIGURATION_SET,
                        sesUntrackedConfigurationSet: hub.SES_UNTRACKED_CONFIGURATION_SET,
                        teamEmailCapMode: 'enforce',
                        teamEmailTierDailyCaps: [200],
                    },
                    hub.integrationManager,
                    configService,
                    hub.ENCRYPTION_SALT_KEYS,
                    hub.SITE_URL,
                    new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
                    new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
                    new RecipientsManagerService(hub.postgres),
                    null,
                    { report: jest.fn() },
                    undefined,
                    null,
                    { claimAllOrNothing, claimUpTo } as unknown as RateLimiterService
                )
                cappedSendSpy = jest.spyOn(cappedService.sesV2Client!, 'send') as any
                cappedSendSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            })

            afterEach(() => {
                jest.restoreAllMocks()
            })

            const buildEnforcedService = (
                name: string,
                dailyCap: number
            ): { service: EmailService; sendSpy: jest.SpyInstance; limiter: RateLimiterService } => {
                const redis = createRedisV2PoolFromConfig({
                    connection: hub.CDP_REDIS_HOST
                        ? {
                              url: hub.CDP_REDIS_HOST,
                              options: { port: hub.CDP_REDIS_PORT, password: hub.CDP_REDIS_PASSWORD },
                          }
                        : { url: hub.REDIS_URL },
                    poolMinSize: hub.REDIS_POOL_MIN_SIZE,
                    poolMaxSize: hub.REDIS_POOL_MAX_SIZE,
                })
                const limiter = new RateLimiterService(redis, { name })
                const configService = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)
                jest.spyOn(configService, 'getEmailSendingTier').mockResolvedValue(0)
                const service = new EmailService(
                    {
                        sesAccessKeyId: hub.SES_ACCESS_KEY_ID,
                        sesSecretAccessKey: hub.SES_SECRET_ACCESS_KEY,
                        sesRegion: hub.SES_REGION,
                        sesEndpoint: hub.SES_ENDPOINT,
                        sesTrackedConfigurationSet: hub.SES_TRACKED_CONFIGURATION_SET,
                        sesUntrackedConfigurationSet: hub.SES_UNTRACKED_CONFIGURATION_SET,
                        teamEmailCapMode: 'enforce',
                        teamEmailTierDailyCaps: [dailyCap],
                    },
                    hub.integrationManager,
                    configService,
                    hub.ENCRYPTION_SALT_KEYS,
                    hub.SITE_URL,
                    new EmailTrackingCodeSigner(hub.ENCRYPTION_SALT_KEYS, hub.CDP_EMAIL_TRACKING_URL),
                    new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv()),
                    new RecipientsManagerService(hub.postgres),
                    null,
                    { report: jest.fn() },
                    undefined,
                    null,
                    limiter
                )
                const sendSpy = jest.spyOn(service.sesV2Client!, 'send') as any
                sendSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                return { service, sendSpy, limiter }
            }

            it.each([
                // A reserved slot is exclusive and is parked on exactly; spreading it would
                // collide it with the slot in front.
                ['parks exactly on a reserved slot', 30 * 60 * 1000, true, 30 * 60 * 1000, 30 * 60 * 1000],
                // Past the horizon nothing is reserved: every overflow caller gets the same
                // wake back and spreads itself 1x-2x across the horizon.
                [
                    'spreads an overflow wake across the horizon',
                    60 * 60 * 1000,
                    false,
                    60 * 60 * 1000,
                    2 * 60 * 60 * 1000,
                ],
            ])('%s', async (_name, retryAfterMs, reserved, minMs, maxMs) => {
                claimAllOrNothing.mockResolvedValue({ granted: false, retryAfterMs, reserved })

                const before = Date.now()
                const result = await cappedService.executeSendEmail(invocation)

                expect(cappedSendSpy).not.toHaveBeenCalled()
                expect(result.error).toBeUndefined()
                expect(result.finished).toBe(false)
                // The reschedule must carry the email payload forward, same as the workflow limit.
                expect(result.invocation.queueParameters).toEqual(invocation.queueParameters)
                // The flag labels the eventual send's queue wait, so alerts can leave out the cap delay.
                expect(result.invocation.queueMetadata).toEqual({ ...invocation.queueMetadata, teamCapped: true })
                const scheduledMs = result.invocation.queueScheduledAt!.toMillis()
                expect(scheduledMs).toBeGreaterThanOrEqual(before + minMs)
                expect(scheduledMs).toBeLessThan(before + maxMs + 5000)
                // A real denial names the cap it hit, which is what makes the limiter-fault case
                // above distinguishable to the customer reading the run's logs.
                expect(result.logs.map((log) => log.message).join(' ')).toContain('reached its email sending limit of')
            })

            it('retries on the token bucket cadence when the limiter reports no horizon', async () => {
                // A Valkey fault denies with no horizon. Parking on the daily cap's pacing
                // interval would hold the email long after the limiter recovered.
                jest.spyOn(Math, 'random').mockReturnValue(0)
                claimAllOrNothing.mockResolvedValue({ granted: false, retryAfterMs: null, reserved: false })

                const before = Date.now()
                const result = await cappedService.executeSendEmail(invocation)

                expect(cappedSendSpy).not.toHaveBeenCalled()
                expect(result.finished).toBe(false)
                const scheduledMs = result.invocation.queueScheduledAt!.toMillis()
                expect(scheduledMs).toBeGreaterThanOrEqual(before + 5 * 60 * 1000)
                expect(scheduledMs).toBeLessThan(before + 5 * 60 * 1000 + 5000)
                // No cap was reached, so the customer must not be told they hit one.
                const messages = result.logs.map((log) => log.message).join(' ')
                expect(messages).not.toContain('reached its email sending limit')
                expect(messages).toContain("Could not check this project's email sending limit")
            })

            it('sends a transactional email past the cap and charges the bucket anyway', async () => {
                claimAllOrNothing.mockResolvedValue({ granted: false, retryAfterMs: 30 * 60 * 1000, reserved: true })
                invocation.hogFunction.metadata = { message_category_type: 'transactional' }

                const result = await cappedService.executeSendEmail(invocation)

                expect(result.finished).toBe(true)
                expect(cappedSendSpy).toHaveBeenCalledTimes(1)
                expect(result.invocation.queueScheduledAt).toBeUndefined()
                expect(claimAllOrNothing).not.toHaveBeenCalled()
                expect(claimUpTo).toHaveBeenCalledTimes(1)
                // No cap was applied, so the customer must not be told one was.
                expect(result.logs.map((log) => log.message).join(' ')).not.toContain('reached its email sending limit')
            })

            it('sends when the claim is granted', async () => {
                claimAllOrNothing.mockResolvedValue({ granted: true, retryAfterMs: null, reserved: false })

                const result = await cappedService.executeSendEmail(invocation)

                // The reservation horizon must reach the limiter, or denials fall back to
                // shared-horizon wakes and a denied backlog re-herds.
                expect(claimAllOrNothing).toHaveBeenCalledWith(expect.anything(), 60 * 60 * 1000)
                expect(result.finished).toBe(true)
                expect(cappedSendSpy).toHaveBeenCalled()
            })

            // A team over its tier cap must not slow anyone else down: its denied sends get
            // their own future slots instead of all waking together, and another team's send
            // goes straight out. Runs against the real limiter.
            it('spreads a capped team over distinct slots while another team keeps sending', async () => {
                const dailyCap = 8640
                const {
                    service: enforcedService,
                    sendSpy: enforcedSendSpy,
                    limiter,
                } = buildEnforcedService('team-email-cap-test', dailyCap)

                // Drain the capped team's bucket so every send below is a denial. The
                // 0.1 tokens/s refill makes the slot spacing 10s, far above test wall-clock.
                const bucket = teamEmailCapBucket(team.id, dailyCap)
                await limiter.claimUpTo({ ...bucket, requested: dailyCap })

                const parkedAt: number[] = []
                for (let i = 0; i < 4; i++) {
                    const denied = await enforcedService.executeSendEmail(invocation)
                    expect(denied.finished).toBe(false)
                    parkedAt.push(denied.invocation.queueScheduledAt!.toMillis())
                }
                // Distinct slots one token interval apart, not a herd at the shared horizon.
                for (let i = 1; i < parkedAt.length; i++) {
                    const gapMs = parkedAt[i] - parkedAt[i - 1]
                    expect(gapMs).toBeGreaterThan(9_000)
                    expect(gapMs).toBeLessThan(11_000)
                }

                // A second team's buckets are cold, so its send goes straight out. Tier caps
                // isolate per team; the capped team's backlog must not reach anyone else.
                const otherTeam = (await createTestTeamFixture(hub.postgres)).team
                await insertIntegration(hub.postgres, otherTeam.id, {
                    id: otherTeam.id + 1,
                    kind: 'email',
                    config: {
                        email: '[email protected]',
                        name: 'Test User',
                        domain: 'posthog.com',
                        verified: true,
                        provider: 'ses',
                    },
                })
                const other = createExampleInvocation({ team_id: otherTeam.id, id: 'function-other-team' })
                other.id = 'invocation-other-team'
                other.state.vmState = { stack: [] } as any
                other.queueParameters = createEmailParams()
                other.queueParameters.from = { integrationId: otherTeam.id + 1 }
                const otherResult = await enforcedService.executeSendEmail(other)

                expect(otherResult.finished).toBe(true)
                expect(enforcedSendSpy).toHaveBeenCalledTimes(1)
            })

            // Enforce mode has only ever issued claimAllOrNothing against real Valkey, so
            // transactional through claimUpTo has never run there. Real limiter.
            it('charges a transactional send against the real bucket without delaying it', async () => {
                const dailyCap = 50
                const {
                    service: enforcedService,
                    sendSpy: enforcedSendSpy,
                    limiter,
                } = buildEnforcedService('team-email-cap-transactional-test', dailyCap)

                // A team of its own, so the buckets start cold whatever else touched Valkey.
                const capTeam = (await createTestTeamFixture(hub.postgres)).team
                await insertIntegration(hub.postgres, capTeam.id, {
                    id: capTeam.id + 1,
                    kind: 'email',
                    config: {
                        email: '[email protected]',
                        name: 'Test User',
                        domain: 'posthog.com',
                        verified: true,
                        provider: 'ses',
                    },
                })
                const sendFor = (id: string, transactional: boolean): CyclotronJobInvocationHogFunction => {
                    const next = createExampleInvocation({ team_id: capTeam.id, id: `function-${id}` })
                    next.id = `invocation-${id}`
                    next.state.vmState = { stack: [] } as any
                    next.queueParameters = createEmailParams()
                    next.queueParameters.from = { integrationId: capTeam.id + 1 }
                    if (transactional) {
                        next.hogFunction.metadata = { message_category_type: 'transactional' }
                    }
                    return next
                }

                // Leave one token, so the next send can show the charge before the cap closes.
                const bucket = teamEmailCapBucket(capTeam.id, dailyCap)
                await limiter.claimUpTo({ ...bucket, requested: dailyCap - 1 })

                // The charge: this send takes the last token rather than riding past the bucket.
                const charged = await enforcedService.executeSendEmail(sendFor('charged', true))
                expect(charged.finished).toBe(true)
                expect(enforcedSendSpy).toHaveBeenCalledTimes(1)

                // Control: the cap really is closed now, so a marketing send parks.
                const marketing = await enforcedService.executeSendEmail(sendFor('marketing', false))
                expect(marketing.finished).toBe(false)
                expect(enforcedSendSpy).toHaveBeenCalledTimes(1)

                // The exemption: a transactional send still goes out against the closed cap.
                const transactional = await enforcedService.executeSendEmail(sendFor('transactional', true))
                expect(transactional.finished).toBe(true)
                expect(transactional.invocation.queueScheduledAt).toBeUndefined()
                expect(enforcedSendSpy).toHaveBeenCalledTimes(2)
            })
        })
    })
    describe('native email sending with maildev', () => {
        let invocation: CyclotronJobInvocationHogFunction
        const mailDevAPI = new MailDevAPI()
        beforeEach(async () => {
            const actualFetch = jest.requireActual('~/common/utils/request').fetch as jest.Mock
            mockFetch.mockImplementation((...args: any[]): Promise<any> => {
                return actualFetch(...args) as any
            })
            await insertIntegration(hub.postgres, team.id, {
                id: getIntegrationId(1),
                kind: 'email',
                config: {
                    email: '[email protected]',
                    name: 'Test User',
                    domain: 'posthog.com',
                    verified: true,
                    provider: 'maildev',
                },
            })
            invocation = createExampleInvocation({ team_id: team.id, id: 'function-1' })
            invocation.id = 'invocation-1'
            invocation.state.vmState = {
                stack: [],
            } as any
            invocation.queueParameters = createEmailParams({ from: { integrationId: 1 } })
            await mailDevAPI.clearEmails()
        })
        it.each([
            ['a plain recipient name', 'Test User'],
            ['a non-ASCII recipient name', 'Café "Müller"'],
        ])('should send an email to %s', async (_desc, recipientName) => {
            invocation.queueParameters = createEmailParams({
                to: { email: '[email protected]', name: recipientName },
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            await waitForExpect(async () => expect(mailDevAPI.getEmails()).resolves.toHaveLength(1))
            const emails = await mailDevAPI.getEmails()
            expect(emails).toHaveLength(1)
            expect(emails[0]).toMatchObject({
                from: [{ address: '[email protected]', name: 'Test User' }],
                html: 'Test HTML',
                subject: 'Test Subject',
                text: 'Test Text',
                to: [{ address: '[email protected]', name: recipientName }],
            })
        })
        it('should include tracking code in the email with distinct_id', async () => {
            invocation.queueParameters = createEmailParams({
                html: '<body>Hi! <a href="https://example.com">Click me</a></body>',
            })
            await service.executeSendEmail(invocation)
            await waitForExpect(async () => expect(mailDevAPI.getEmails()).resolves.toHaveLength(1))
            const emails = await mailDevAPI.getEmails()
            expect(emails).toHaveLength(1)
            // ph_id may be unsigned (base64url only) or signed (base64url + `.` + signature) depending on
            // ENCRYPTION_SALT_KEYS. Match the structure, not the exact value.
            expect(emails[0].html).toMatch(
                /^<body>Hi! <a href="http:\/\/localhost:8010\/public\/m\/redirect\?ph_id=[A-Za-z0-9._-]+&ph_sig=[A-Za-z0-9_-]+&target=https%3A%2F%2Fexample\.com">Click me<\/a><img src="http:\/\/localhost:8010\/public\/m\/pixel\?ph_id=[A-Za-z0-9._-]+" style="display: none;" \/><\/body>$/
            )
        })
    })
    describe('native email sending with ses', () => {
        let invocation: CyclotronJobInvocationHogFunction
        let sendEmailSpy: jest.SpyInstance
        beforeEach(async () => {
            const actualFetch = jest.requireActual('~/common/utils/request').fetch as jest.Mock
            mockFetch.mockImplementation((...args: any[]): Promise<any> => {
                return actualFetch(...args) as any
            })
            await insertIntegration(hub.postgres, team.id, {
                id: getIntegrationId(1),
                kind: 'email',
                config: {
                    email: '[email protected]',
                    name: 'Test User',
                    domain: 'posthog-test.com',
                    verified: true,
                    provider: 'ses',
                },
            })
            invocation = createExampleInvocation({ team_id: team.id, id: 'function-1' })
            invocation.id = 'invocation-1'
            invocation.state.vmState = {
                stack: [],
            } as any
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
            })
            sendEmailSpy = jest.spyOn(service.sesV2Client!, 'send')
        })

        it('should error if not verified', async () => {
            sendEmailSpy.mockRejectedValue(new Error('Email address not verified "Test User" <[email protected]>'))
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toEqual(
                'Failed to send email via SES: Email address not verified "Test User" <[email protected]>'
            )
        })

        it.each([
            [
                'an ordinary template',
                {},
                '$pageview',
                [{ Name: 'ph_id', Value: expect.stringMatching(/^[A-Za-z0-9_-]+$/) }],
            ],
            [
                'a sensitive template',
                { sensitive: true },
                '$pageview',
                [
                    { Name: 'ph_id', Value: expect.stringMatching(/^[A-Za-z0-9_-]+$/) },
                    { Name: 'ph_sensitive', Value: 'true' },
                ],
            ],
            [
                'a transactional email run',
                {},
                TRANSACTIONAL_EMAIL_EVENT,
                [
                    { Name: 'ph_id', Value: expect.stringMatching(/^[A-Za-z0-9_-]+$/) },
                    { Name: 'ph_email_status', Value: 'true' },
                ],
            ],
        ])('should send an email if verified, for %s', async (_name, extraMetadata, triggerEvent, expectedTags) => {
            invocation.hogFunction.metadata = { message_category_type: 'transactional', ...extraMetadata }
            invocation.state.globals.event.event = triggerEvent
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            expect(result.emailSendResult).toEqual({ status: 'accepted' })
            expect(sendEmailSpy).toHaveBeenCalledTimes(1)
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            // The SES tag carries the short unsigned code (no dot); the signed code (with distinct_id)
            // rides in the header.
            expect(sentCommand.input).toMatchObject({
                ConfigurationSetName: 'posthog-messaging',
                Content: {
                    Simple: {
                        Body: {
                            Html: { Charset: 'UTF-8', Data: 'Test HTML' },
                            Text: { Charset: 'UTF-8', Data: 'Test Text' },
                        },
                        Subject: { Charset: 'UTF-8', Data: 'Test Subject' },
                    },
                },
                Destination: { ToAddresses: ['"Test User" <[email protected]>'] },
                EmailTags: expectedTags,
                FeedbackForwardingEmailAddress: '[email protected]',
                FromEmailAddress: '"Test User" <[email protected]>',
            })
        })

        describe('attachments', () => {
            let attachments: EmailAttachmentsService
            let assertPool: Pool
            const pdfBytes = Buffer.from([0x25, 0x50, 0x44, 0x46, 0x00, 0x9f, 0xff])
            const files = decodeAttachments({
                tracking: { captureEngagement: false },
                attachments: [
                    {
                        filename: 'report.pdf',
                        content: pdfBytes.toString('base64'),
                        contentType: 'application/pdf',
                    },
                    {
                        filename: 'logo.png',
                        content: Buffer.from('png bytes').toString('base64'),
                        contentType: 'image/png',
                        contentId: 'logo',
                    },
                ],
            })

            beforeEach(() => {
                attachments = new EmailAttachmentsService(hub.CYCLOTRON_NODE_DATABASE_URL)
                service['emailAttachmentsService'] = attachments
                assertPool = new Pool({ connectionString: hub.CYCLOTRON_NODE_DATABASE_URL })
                invocation.id = new UUIDT().toString()
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                    attachments: attachmentMetadata(files),
                })
            })

            afterEach(async () => {
                await attachments.stop()
                await assertPool.end()
            })

            it.each([
                ['on the first try', null],
                [
                    'on the retry after an SES throttle',
                    () => sendEmailSpy.mockRejectedValueOnce(new ThrottlingException('Rate exceeded')),
                ],
                [
                    'on the retry after the attachment store fails to answer',
                    () =>
                        jest
                            .spyOn(attachments, 'load')
                            .mockRejectedValueOnce(new Error('timeout exceeded when trying to connect')),
                ],
            ])('delivers the files to SES as Base64 attachments %s', async (_name, failFirstTry) => {
                failFirstTry?.()
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                await attachments.store(invocation.id, team.id, files)

                let result = await service.executeSendEmail(invocation)
                if (failFirstTry) {
                    expect(result.finished).toBe(false)
                    expect(result.error).toBeUndefined()
                    expect(result.invocation.queueScheduledAt!.toMillis()).toBeGreaterThan(Date.now())
                    result = await service.executeSendEmail(result.invocation)
                }

                expect(result.finished).toBe(true)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls.at(-1)![0] as { input: any }
                expect(sentCommand.input.Content.Simple.Attachments).toEqual([
                    {
                        RawContent: pdfBytes,
                        FileName: 'report.pdf',
                        ContentType: 'application/pdf',
                        ContentId: undefined,
                        ContentDisposition: 'ATTACHMENT',
                        ContentTransferEncoding: 'BASE64',
                    },
                    {
                        RawContent: Buffer.from('png bytes'),
                        FileName: 'logo.png',
                        ContentType: 'image/png',
                        ContentId: 'logo',
                        ContentDisposition: 'INLINE',
                        ContentTransferEncoding: 'BASE64',
                    },
                ])
            })

            it.each([
                ['no row is stored', async () => {}],
                [
                    'the files under this job id belong to another team',
                    async () => {
                        await attachments.store(invocation.id, team.id + 1, files)
                    },
                ],
                [
                    'a stored file does not match its checksum',
                    async () => {
                        await attachments.store(invocation.id, team.id, files)
                        await assertPool.query(
                            `UPDATE cyclotron_email_attachments SET content = 'other bytes' WHERE job_id = $1 AND position = 1`,
                            [invocation.id]
                        )
                    },
                ],
            ])('fails the send as attachments_missing and sends nothing when %s', async (_name, arrange) => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                await arrange()

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.finished).toBe(true)
                expect(result.error).toMatch(/^attachments_missing: /)
            })
        })

        const sesAccepts = (): void => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
        }
        const sesRejects = (): void => {
            sendEmailSpy.mockRejectedValue(new Error('SES error'))
        }
        const teamSuspended = (): void => {
            sesAccepts()
            jest.spyOn(service['teamWorkflowsConfigService'], 'getEmailSendingSuspension').mockResolvedValue('staff')
        }
        const workflowPaused = (): void => {
            sesAccepts()
            invocation.hogFunction.metadata = { email_sending_paused_at: '2026-01-01T00:00:00Z' }
        }
        const recipientMissing = (): void => {
            sesAccepts()
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                to: { email: '', name: 'Test User' },
            })
        }
        const recipientSuppressed = (): void => {
            sesAccepts()
            jest.spyOn(service['emailSuppressionService'], 'isSuppressed').mockResolvedValue(true)
        }

        it.each([
            ['a transactional email that SES accepts', TRANSACTIONAL_EMAIL_EVENT, false, sesAccepts, 'sent', ''],
            [
                'a transactional email that SES rejects',
                TRANSACTIONAL_EMAIL_EVENT,
                false,
                sesRejects,
                'failed',
                'provider_error',
            ],
            [
                'a transactional email skipped for a suspended team',
                TRANSACTIONAL_EMAIL_EVENT,
                false,
                teamSuspended,
                'failed',
                'sending_suspended',
            ],
            [
                'a transactional email skipped for a paused workflow',
                TRANSACTIONAL_EMAIL_EVENT,
                false,
                workflowPaused,
                'failed',
                'sending_paused',
            ],
            [
                'a transactional email skipped for a missing recipient',
                TRANSACTIONAL_EMAIL_EVENT,
                false,
                recipientMissing,
                'failed',
                'missing_recipient',
            ],
            [
                'a transactional email skipped for a suppressed recipient',
                TRANSACTIONAL_EMAIL_EVENT,
                false,
                recipientSuppressed,
                'failed',
                'recipient_suppressed',
            ],
            ['a test send of a transactional email', TRANSACTIONAL_EMAIL_EVENT, true, sesAccepts, null, null],
            [
                'a skipped test send of a transactional email',
                TRANSACTIONAL_EMAIL_EVENT,
                true,
                teamSuspended,
                null,
                null,
            ],
            ['a workflow email that SES accepts', '$pageview', false, sesAccepts, null, null],
            ['a workflow email that SES rejects', '$pageview', false, sesRejects, null, null],
            ['a skipped workflow email', '$pageview', false, recipientSuppressed, null, null],
        ])('records the status of %s', async (_name, triggerEvent, isTest, setup, status, reason) => {
            const produce = jest.fn().mockResolvedValue(undefined)
            const emailStatusService = new EmailStatusService(
                { produce } as unknown as IngestionOutputs<EmailStatusOutput>,
                { EMAIL_STATUS_ENABLED: true }
            )
            service['emailStatusService'] = emailStatusService
            invocation.id = new UUIDT().toString()
            invocation.state.globals.event.event = triggerEvent
            setup()

            await service.executeSendEmail(invocation, isTest)
            await emailStatusService.flush()

            const rows = produce.mock.calls.map(([, message]) => parseJSON(message.value.toString()))
            const sendingDomain = status === 'sent' || reason === 'provider_error' ? 'posthog-test.com' : ''
            expect(rows).toEqual(
                status
                    ? [
                          expect.objectContaining({
                              team_id: team.id,
                              message_id: invocation.id,
                              status,
                              reason,
                              sending_domain: sendingDomain,
                          }),
                      ]
                    : []
            )
        })

        it('records a send-time metric for normal sends but not for test sends', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

            const normal = await service.executeSendEmail(invocation)
            expect(normal.metrics.map((m) => m.metric_name)).toContain('email_sent')

            const testSend = await service.executeSendEmail(invocation, true)
            expect(testSend.metrics).toEqual([])
        })

        describe('suppression enforcement at send time', () => {
            // Guards the "email hog function destination bypasses shouldSkipAction, so suppression
            // isn't enforced on that path" gap. executeSendEmail is the single choke point every
            // outbound send goes through — the suppression check has to live here so it can't be
            // skipped just by choosing a different upstream code path.
            it('does not call SES when the recipient is on the suppression list', async () => {
                const isSuppressedSpy = jest
                    .spyOn(service['emailSuppressionService'], 'isSuppressed')
                    .mockResolvedValue(true)
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(isSuppressedSpy).toHaveBeenCalled()
                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.metrics.map((m) => m.metric_name)).toContain('email_suppressed')
                expect(result.metrics.map((m) => m.metric_name)).not.toContain('email_sent')
            })

            it('moves the first deliverable cc address to To when the To address is suppressed', async () => {
                const suppressed = new Set(['[email protected]', '[email protected]', '[email protected]'])
                jest.spyOn(service['emailSuppressionService'], 'isSuppressed').mockImplementation((_teamId, email) =>
                    Promise.resolve(suppressed.has(email))
                )
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                    cc: '"Bounced" <[email protected]>, [email protected], [email protected]',
                    bcc: '[email protected]',
                })

                const result = await service.executeSendEmail(invocation)

                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.Destination).toEqual({
                    ToAddresses: ['[email protected]'],
                    CcAddresses: ['[email protected]'],
                })
                expect(result.metrics.map((m) => m.metric_name)).toContain('email_sent')
                expect(result.logs.map((l) => l.message).join(' ')).toContain(
                    '[email protected], [email protected], [email protected]'
                )
            })

            it('calls SES when the recipient is not suppressed', async () => {
                jest.spyOn(service['emailSuppressionService'], 'isSuppressed').mockResolvedValue(false)
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).toHaveBeenCalledTimes(1)
                expect(result.metrics.map((m) => m.metric_name)).toContain('email_sent')
            })
        })

        // A person without an email property renders an empty `to`. Counting that as email_failed
        // lets one project's data trip the platform send failure rate alert.
        it.each([
            ['an empty string', ''],
            ['only whitespace', '   '],
            ['no value', undefined],
        ])('skips the send without SES or email_failed when the recipient is %s', async (_label, email) => {
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                to: { email: email as string, name: 'Test User' },
            })
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

            const result = await service.executeSendEmail(invocation)

            expect(sendEmailSpy).not.toHaveBeenCalled()
            expect(result.error).toBeUndefined()
            expect(result.metrics.map((m) => m.metric_name)).toEqual(['email_missing_recipient'])
            expect(result.skipped).toBe(true)
            expect(result.emailSendResult).toEqual({
                status: 'skipped',
                reason: expect.stringContaining('the recipient has no email address'),
            })
            expect(invocation.state.vmState?.stack).toEqual([{ success: false }])
        })

        it.each([
            ['a workflow send', true, false, 1],
            ['a workflow test send', true, true, 0],
            ['a hog function send', false, false, 0],
        ])(
            'reports a missing recipient as a blocked send only for a real workflow send: %s',
            async (_name, fromWorkflow, isTest, reports) => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                    to: { email: '', name: 'Test User' },
                })
                const sentInvocation = fromWorkflow
                    ? { ...invocation, hogFlow: new FixtureHogFlowBuilder().withTeamId(team.id).build() }
                    : invocation

                await service.executeSendEmail(sentInvocation, isTest)

                expect(workflowsActivationReporter.report.mock.calls).toEqual(
                    Array(reports).fill([
                        team.id,
                        'workflows send blocked',
                        { reason: 'missing_recipient', channel: 'email', workflow_id: invocation.functionId },
                    ])
                )
            }
        )

        describe('SES tenant attribution', () => {
            it('attributes the send to the team tenant', async () => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.TenantName).toEqual(`team-${team.id}`)
            })

            it('attributes test-panel sends too — they are real SES sends', async () => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation, true)

                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.TenantName).toEqual(`team-${team.id}`)
            })
        })

        describe('team suspension enforcement at send time', () => {
            // Guards both suspension switches: while a team is suspended, no send path may
            // reach SES — including editor test sends, which count against the tenant too.
            // These write a real config row so they also cover the service's SELECT; mocking
            // getEmailSendingSuspension would pass with the column missing from the query.
            const suspendTeam = async (): Promise<void> => {
                await hub.postgres.query(
                    PostgresUse.COMMON_WRITE,
                    `INSERT INTO workflows_teamworkflowsconfig
                        (team_id, capture_workflows_engagement_events, email_tracking_consent_mode,
                         email_sending_suspended_at, email_sending_suspension_reason)
                     VALUES ($1, false, 'off', now(), 'testing suspension')
                     ON CONFLICT (team_id) DO UPDATE SET email_sending_suspended_at = now()`,
                    [team.id],
                    'test-suspend-email-sending'
                )
            }

            it('does not call SES while the team is suspended and records email_suspended', async () => {
                await suspendTeam()
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.metrics.map((m) => m.metric_name)).toEqual(['email_suspended'])
                expect(result.emailSendResult).toEqual({
                    status: 'skipped',
                    reason: 'Skipping send: email sending is suspended for this project. Contact support to get sending re-enabled.',
                })
                expect(invocation.state.vmState?.stack).toEqual([{ success: false }])
            })

            it('blocks editor test sends while suspended without recording metrics', async () => {
                await suspendTeam()
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation, true)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.metrics).toEqual([])
            })

            // A per-workflow pause holds one workflow's email while the rest of the project keeps
            // sending. Same choke point as the team switch above, so no upstream route bypasses it.
            it('does not call SES while the workflow is paused and records email_paused', async () => {
                invocation.hogFunction.metadata = {
                    email_sending_paused_at: '2026-01-01T00:00:00Z',
                    email_sending_paused_reason: 'Spam complaints reached 2% of the 400 emails sent.',
                }
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.metrics.map((m) => m.metric_name)).toEqual(['email_paused'])
                expect(result.emailSendResult?.status).toBe('skipped')
                expect(result.emailSendResult?.reason).toContain('Resume it from the workflow page')
                expect(invocation.state.vmState?.stack).toEqual([{ success: false }])
                expect(result.logs.map((l) => l.message).join(' ')).toContain('Spam complaints reached 2%')
                // Flags the skip so the flow-level billing gate charges nothing for a send that never sent.
                expect(result.skipped).toBe(true)
            })

            it('tells a staff-paused workflow to contact support instead of the resume button', async () => {
                invocation.hogFunction.metadata = {
                    email_sending_paused_at: '2026-01-01T00:00:00Z',
                    email_sending_paused_reason:
                        "PostHog staff paused this workflow's email to protect delivery for everyone.",
                    email_sending_paused_by: 'staff',
                }
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                const messages = result.logs.map((l) => l.message).join(' ')
                expect(messages).toContain('Contact support')
                expect(messages).not.toContain('Resume it from the workflow page')
            })

            it('blocks editor test sends while the workflow is paused without recording metrics', async () => {
                invocation.hogFunction.metadata = { email_sending_paused_at: '2026-01-01T00:00:00Z' }
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation, true)

                expect(sendEmailSpy).not.toHaveBeenCalled()
                expect(result.metrics).toEqual([])
            })

            it('sends once the workflow pause is cleared', async () => {
                invocation.hogFunction.metadata = {
                    email_sending_paused_at: null,
                    email_sending_paused_reason: null,
                }
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).toHaveBeenCalledTimes(1)
                expect(result.metrics.map((m) => m.metric_name)).toContain('email_sent')
            })

            const setProviderTenantStatus = async (status: string): Promise<void> => {
                await hub.postgres.query(
                    PostgresUse.COMMON_WRITE,
                    // email_sending_suspension_reason is NOT NULL and its default is Django-side,
                    // not on the column, so a raw INSERT has to supply it.
                    `INSERT INTO workflows_teamworkflowsconfig
                        (team_id, capture_workflows_engagement_events, email_tracking_consent_mode,
                         email_sending_suspension_reason, ses_tenant_sending_status)
                     VALUES ($1, false, 'off', '', $2)
                     ON CONFLICT (team_id) DO UPDATE SET ses_tenant_sending_status = $2`,
                    [team.id, status],
                    'test-set-ses-tenant-sending-status'
                )
            }

            // A paused provider tenant rejects every send, so the send path has to read the stored
            // state. Only DISABLED blocks: REINSTATED is what a tenant the provider has restored
            // reads, so treating any non-ENABLED status as paused would withhold accepted sends.
            it.each([
                ['DISABLED', 0, 'email_suspended'],
                ['REINSTATED', 1, 'email_sent'],
            ])('provider tenant status %s: %i SES calls, records %s', async (status, sesCalls, metricName) => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                await setProviderTenantStatus(status as string)

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).toHaveBeenCalledTimes(sesCalls as number)
                expect(result.metrics.map((m) => m.metric_name)).toContain(metricName)
            })

            // The send path caches this row for minutes, so a pause that lands after the first read
            // would keep sending — and a reinstatement would keep blocking — until the entry aged
            // out. The provider state sync announces each change to close that window.
            it('picks up a provider status change announced while the config is cached', async () => {
                const configService = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)
                await setProviderTenantStatus('ENABLED')
                expect(await configService.getEmailSendingSuspension(team.id)).toBeNull()

                await setProviderTenantStatus('DISABLED')

                await waitForExpect(async () => {
                    // Republished every poll: subscribing is asynchronous, so the first publish can
                    // land before this subscriber is listening. Marking for refresh is idempotent.
                    await hub.pubSub.publish('reload-team-workflows-config', JSON.stringify({ teamId: team.id }))
                    expect(await configService.getEmailSendingSuspension(team.id)).toEqual('provider')
                }, 3000)
            })

            // The suspension check fails open. A load that throws would therefore let a suspended team send.
            it.each(INVALID_TEAM_ID_KEYS)(
                'keeps a suspended team blocked when invalid team id %p shares its config load',
                async (key) => {
                    await suspendTeam()
                    const configService = new TeamWorkflowsConfigService(hub.postgres, hub.pubSub)

                    const [suspension, invalidTeamConfig] = await Promise.all([
                        configService.getEmailSendingSuspension(team.id),
                        configService.get(key as unknown as number),
                    ])

                    expect(suspension).toEqual('staff')
                    expect(invalidTeamConfig).toMatchObject({ email_sending_suspended: false })
                }
            )

            it('fails open when the suspension lookup errors', async () => {
                // The config lookup rejecting must never block a legitimate send. Rejects once:
                // the suspension check is the first config read; later reads use the real loader.
                jest.spyOn(service['teamWorkflowsConfigService'], 'get').mockRejectedValueOnce(new Error('pg down'))
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })

                const result = await service.executeSendEmail(invocation)

                expect(sendEmailSpy).toHaveBeenCalledTimes(1)
                expect(result.metrics.map((m) => m.metric_name)).toContain('email_sent')
            })
        })

        it('should include cc addresses in SES destination', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                cc: '[email protected], [email protected]',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.Destination.CcAddresses).toEqual(['[email protected]', '[email protected]'])
        })

        it('should include bcc addresses in SES destination', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                bcc: '[email protected]',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.Destination.BccAddresses).toEqual(['[email protected]'])
        })

        it('should not include cc/bcc in SES destination when not provided', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.Destination.CcAddresses).toBeUndefined()
            expect(sentCommand.input.Destination.BccAddresses).toBeUndefined()
        })

        it('should not include cc/bcc in SES destination when empty strings', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                cc: '',
                bcc: '  ',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.Destination.CcAddresses).toBeUndefined()
            expect(sentCommand.input.Destination.BccAddresses).toBeUndefined()
        })

        it('should not include replyTo if not in params', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.ReplyToAddresses).toBeUndefined()
        })

        it('should include single replyTo address if in params', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                replyTo: 'Customer Service <[email protected]>',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.ReplyToAddresses).toEqual(['Customer Service <[email protected]>'])
        })

        it('should split multiple comma-separated replyTo addresses', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                replyTo: '[email protected], [email protected], Customer Service <[email protected]>',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.ReplyToAddresses).toEqual([
                '[email protected]',
                '[email protected]',
                'Customer Service <[email protected]>',
            ])
        })

        it.each([
            ['uses the sender default when the step has none', undefined, ['[email protected]']],
            ['uses the sender default when the step has no parsed addresses', ' , ', ['[email protected]']],
            ['keeps the step reply-to over the sender default', '[email protected]', ['[email protected]']],
        ])('%s', async (_, replyTo, expected) => {
            await insertIntegration(hub.postgres, team.id, {
                id: getIntegrationId(2),
                kind: 'email',
                config: {
                    email: '[email protected]',
                    name: 'Test User',
                    domain: 'posthog-test.com',
                    verified: true,
                    provider: 'ses',
                    reply_to: '[email protected]',
                },
            })
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({ from: { integrationId: 2 }, replyTo })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.ReplyToAddresses).toEqual(expected)
        })

        it.each([
            ['text only', { html: '', text: 'Hello, this is a plain text email.' }, ['Text']],
            ['html only, no text', { html: '<p>Hello</p>', text: undefined }, ['Html']],
            ['html only, empty text', { html: '<p>Hello</p>', text: '' }, ['Html']],
        ])('sends only the parts that have content: %s', async (_name, content, expectedParts) => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.hogFunction.metadata = { message_category_type: 'transactional' }
            invocation.queueParameters = CyclotronInvocationQueueParametersEmailSchema.parse(
                createEmailParams({ from: { integrationId: 1 }, ...content })
            )
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(Object.keys(sentCommand.input.Content.Simple.Body)).toEqual(expectedParts)
            if (content.text) {
                expect(sentCommand.input.Content.Simple.Body.Text).toEqual({ Data: content.text, Charset: 'UTF-8' })
            }
        })

        it('should not include preheader span if not in params', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                html: '<tbody>Test email content</tbody>',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            const htmlData = sentCommand.input.Content.Simple.Body.Html.Data
            expect(htmlData).not.toContain('mso-hide:all')
        })

        it.each([
            [
                'a document',
                '<html><body class="email"><table><tbody><tr><td>Hi</td></tr></tbody></table></body></html>',
                /^<html><body class="email"><span style=".*">This is a preview text<\/span><table>/,
            ],
            ['a fragment without tbody', '<p>Hi</p>', /^<span style=".*">This is a preview text<\/span><p>Hi<\/p>$/],
        ])('should include preheader at the start of the body of %s', async (_name, html, expected) => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.queueParameters = createEmailParams({
                from: { integrationId: 1 },
                html,
                preheader: 'This is a preview text',
            })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            expect(sentCommand.input.Content.Simple.Body.Html.Data).toMatch(expected)
        })

        it.each([
            { name: 'a hog function send', fromHogFlow: false, parentRunId: null, expectedSource: {} },
            {
                name: 'a workflow send',
                fromHogFlow: true,
                parentRunId: null,
                expectedSource: { app_source_id: 'function-1', instance_id: 'action-email' },
            },
            {
                name: 'a broadcast send',
                fromHogFlow: true,
                parentRunId: 'batch-run-1',
                expectedSource: { app_source_id: 'batch-run-1', instance_id: 'action-email' },
            },
        ])(
            'includes unsubscribe headers for $name, attributed to the email it came from',
            async ({ fromHogFlow, parentRunId, expectedSource }) => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.hogFunction.metadata = { message_category_type: 'marketing' }
                if (fromHogFlow) {
                    Object.assign(invocation, { hogFlow: { id: 'function-1', version: 1 }, parentRunId })
                    invocation.state.actionId = 'action-email'
                }
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                const headers = sentCommand.input.Content.Simple.Headers
                expect(headers).toEqual(
                    expect.arrayContaining([
                        expect.objectContaining({ Name: 'List-Unsubscribe' }),
                        expect.objectContaining({ Name: 'List-Unsubscribe-Post' }),
                    ])
                )
                const unsubscribeUrl = headers.find((h: { Name: string }) => h.Name === 'List-Unsubscribe').Value
                const token = unsubscribeUrl.match(/messaging-preferences\/([^/]+)\//)[1]
                const validated = new RecipientTokensService(
                    hub.ENCRYPTION_SALT_KEYS,
                    hub.SITE_URL
                ).validatePreferencesToken(token)
                expect(validated).toEqual({
                    valid: true,
                    team_id: team.id,
                    identifier: '[email protected]',
                    ...expectedSource,
                })
            }
        )

        it('should not include unsubscribe headers for transactional emails (but tracking-code header is still set)', async () => {
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.hogFunction.metadata = { message_category_type: 'transactional' }
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            const headerNames = (sentCommand.input.Content.Simple.Headers ?? []).map((h: { Name: string }) => h.Name)
            expect(headerNames).not.toContain('List-Unsubscribe')
            expect(headerNames).not.toContain('List-Unsubscribe-Post')
            expect(headerNames).toContain('X-PostHog-Tracking-Code')
        })

        it.each(['transactional', 'marketing'])(
            'marks a %s send as auto-generated so autoresponders do not answer it',
            async (categoryType) => {
                // Without this an autoresponder answers the workflow, and when the address it
                // answers is a support inbox the reply re-enters the same workflow as a new ticket.
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.hogFunction.metadata = { message_category_type: categoryType }
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.Content.Simple.Headers).toEqual(
                    expect.arrayContaining([{ Name: 'Auto-Submitted', Value: 'auto-generated' }])
                )
            }
        )

        it('attaches the X-PostHog-Tracking-Code header carrying the full signed code', async () => {
            // The header is the authoritative tracking-code carrier (the EmailTag is the
            // bounded backwards-compat fallback). It rides on every outbound message,
            // regardless of transactional vs. marketing category.
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            invocation.hogFunction.metadata = { message_category_type: 'transactional' }
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
            const trackingHeader = sentCommand.input.Content.Simple.Headers.find(
                (h: { Name: string }) => h.Name === 'X-PostHog-Tracking-Code'
            )
            expect(trackingHeader).toBeDefined()
            expect(typeof trackingHeader.Value).toBe('string')
            expect(trackingHeader.Value.length).toBeGreaterThan(0)
            // The SES EmailTag carries a *different* (shorter, unsigned) code so it stays under the
            // 256-char tag-value limit even when distinct_id is long.
            expect(sentCommand.input.EmailTags[0].Value).not.toEqual(trackingHeader.Value)
        })

        describe('per-send tracking gate (tracking_enabled)', () => {
            // Would be tracked if the gate regressed: has an anchor to rewrite and a </body> to pixel.
            const trackableHtml = '<body>Hi! <a href="https://example.com">Click me</a></body>'

            beforeEach(() => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.queueParameters = createEmailParams({ from: { integrationId: 1 }, html: trackableHtml })
                invocation.hogFunction.metadata = { tracking_enabled: false }
            })

            it('skips pixel and link rewriting and uses the untracked configuration set when tracking is off', async () => {
                service['sesConfig'].sesUntrackedConfigurationSet = 'posthog-messaging-untracked'
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.ConfigurationSetName).toEqual('posthog-messaging-untracked')
                expect(sentCommand.input.Content.Simple.Body.Html.Data).toEqual(trackableHtml)
                // Delivery/bounce attribution must survive tracking-off: the untracked configuration
                // set still emits delivery events, and the webhook needs this header to attribute them.
                const headerNames = sentCommand.input.Content.Simple.Headers.map((h: { Name: string }) => h.Name)
                expect(headerNames).toContain('X-PostHog-Tracking-Code')
            })

            it.each([
                {
                    case: 'the workflow and step names',
                    utmParams: undefined,
                    query: 'utm_source=posthog&amp;utm_medium=email&amp;utm_campaign=Spring%20sale&amp;utm_content=Welcome',
                },
                {
                    case: 'rendered custom values',
                    utmParams: { utm_source: 'newsletter', utm_campaign: '{{ "pro" | upcase }}' },
                    query: 'utm_source=newsletter&amp;utm_medium=email&amp;utm_campaign=PRO&amp;utm_content=Welcome',
                },
                {
                    case: 'a rendered value with characters HTML escapes',
                    utmParams: { utm_campaign: '{{ "Starter & Premium" }}' },
                    query: 'utm_source=posthog&amp;utm_medium=email&amp;utm_campaign=Starter%20%26%20Premium&amp;utm_content=Welcome',
                },
                {
                    case: 'the default for a value with a Liquid error',
                    utmParams: { utm_campaign: '{{ person.properties.plan' },
                    query: 'utm_source=posthog&amp;utm_medium=email&amp;utm_campaign=Spring%20sale&amp;utm_content=Welcome',
                },
            ])('tags the links with $case when the step turns UTM tags on', async ({ utmParams, query }) => {
                invocation.hogFunction.metadata = {
                    tracking_enabled: false,
                    utm_tags_enabled: true,
                    utm_params: utmParams,
                    hog_flow_name: 'Spring sale',
                    hog_flow_action_name: 'Welcome',
                }
                const messageAssets = new MessageAssetsService({
                    produce: jest.fn().mockResolvedValue(undefined),
                } as unknown as IngestionOutputs<'message_assets'>)
                const buildRowForEmail = jest.spyOn(messageAssets, 'buildRowForEmail').mockReturnValue(null)
                service['messageAssetsService'] = messageAssets
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                const taggedHtml = `<body>Hi! <a href="https://example.com?${query}">Click me</a></body>`
                expect(sentCommand.input.Content.Simple.Body.Html.Data).toEqual(taggedHtml)
                // The stored copy behind "View email" shows the links the recipient got.
                expect(buildRowForEmail).toHaveBeenCalledWith(
                    expect.anything(),
                    expect.objectContaining({ html: taggedHtml })
                )
            })

            it.each([
                { case: 'an empty list', list: (): string => '', fixedScanner: false },
                { case: 'a list with this team', list: (): string => `${team.id}`, fixedScanner: true },
                { case: 'a list with another team', list: (): string => `${team.id + 1}`, fixedScanner: false },
                { case: 'every team', list: (): string => '*', fixedScanner: true },
            ])('picks the UTM link scanner from $case', async ({ list, fixedScanner }) => {
                service['sesConfig'].utmLinkScannerTeams = list()
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                    html: '<body><a href=https://example.com/pricing>Click me</a></body>',
                })
                invocation.hogFunction.metadata = {
                    tracking_enabled: false,
                    utm_tags_enabled: true,
                    hog_flow_name: 'Spring sale',
                    hog_flow_action_name: 'Welcome',
                }
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.Content.Simple.Body.Html.Data).toEqual(
                    fixedScanner
                        ? '<body><a href="https://example.com/pricing?utm_source=posthog&amp;utm_medium=email&amp;utm_campaign=Spring%20sale&amp;utm_content=Welcome">Click me</a></body>'
                        : '<body><a href=https://example.com/pricing>Click me</a></body>'
                )
            })

            it('falls back to the tracked configuration set when no untracked set is configured, still untracked HTML', async () => {
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
                expect(sentCommand.input.ConfigurationSetName).toEqual('posthog-messaging')
                expect(sentCommand.input.Content.Simple.Body.Html.Data).toEqual(trackableHtml)
            })

            it('records an email_untracked app metric for untracked sends but not for test sends', async () => {
                const normal = await service.executeSendEmail(invocation)
                expect(normal.metrics.map((m) => m.metric_name)).toEqual(
                    expect.arrayContaining(['email_sent', 'email_untracked'])
                )

                const testSend = await service.executeSendEmail(invocation, true)
                expect(testSend.metrics).toEqual([])
            })

            it('marks the captured send event as untracked so customer-built engagement rates can exclude it', async () => {
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'shouldCaptureEngagementEvents'
                ).mockResolvedValue(true)
                const result = await service.executeSendEmail(invocation)
                expect(result.capturedPostHogEvents[0].properties).toMatchObject({
                    $email_tracking_enabled: false,
                })
            })
        })

        describe('recipient tracking consent', () => {
            const trackableHtml = '<body>Hi! <a href="https://example.com">Click me</a></body>'

            const setConsentState = (
                mode: 'off' | 'opt_out' | 'opt_in',
                storedConsent: 'OPTED_IN' | 'OPTED_OUT' | null
            ): void => {
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'getEmailTrackingConsentMode'
                ).mockResolvedValue(mode)
                jest.spyOn((service as any).recipientsManager, 'get').mockResolvedValue(
                    storedConsent
                        ? {
                              id: 'pref-1',
                              team_id: team.id,
                              identifier: '[email protected]',
                              preferences: { $email_tracking: storedConsent },
                              created_at: '',
                              updated_at: '',
                          }
                        : null
                )
            }

            beforeEach(() => {
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                invocation.queueParameters = createEmailParams({ from: { integrationId: 1 }, html: trackableHtml })
                invocation.hogFunction.metadata = { message_category_type: 'marketing' }
            })

            it.each([
                ['off mode ignores consent entirely', 'off', null, true],
                ['opt_out mode tracks recipients with no stored preference', 'opt_out', null, true],
                ['opt_out mode does not track recipients who opted out', 'opt_out', 'OPTED_OUT', false],
                ['opt_in mode does not track recipients with no stored preference', 'opt_in', null, false],
                ['opt_in mode tracks recipients who opted in', 'opt_in', 'OPTED_IN', true],
            ] as [string, 'off' | 'opt_out' | 'opt_in', 'OPTED_IN' | 'OPTED_OUT' | null, boolean][])(
                '%s',
                async (_name, mode, storedConsent, expectTracked) => {
                    setConsentState(mode, storedConsent)
                    const result = await service.executeSendEmail(invocation)
                    expect(result.error).toBeUndefined()
                    const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html
                        .Data
                    if (expectTracked) {
                        // SES sends tag each anchor and let SES report the click, instead of
                        // rewriting the href to a redirect URL. The open pixel is unchanged.
                        expect(sentHtml).toContain('ses:tags="phl:')
                        expect(sentHtml).toContain('ph_id=')
                    } else {
                        expect(sentHtml).toEqual(trackableHtml)
                    }
                }
            )

            it('transactional emails are exempt from consent enforcement', async () => {
                invocation.hogFunction.metadata = { message_category_type: 'transactional' }
                setConsentState('opt_in', null)
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html.Data
                expect(sentHtml).toContain('ses:tags="phl:')
                expect(sentHtml).toContain('ph_id=')
            })

            it('the step-level toggle wins over consent: tracking_enabled false is untracked even for opted-in recipients', async () => {
                invocation.hogFunction.metadata = { message_category_type: 'marketing', tracking_enabled: false }
                setConsentState('opt_in', 'OPTED_IN')
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html.Data
                expect(sentHtml).toEqual(trackableHtml)
            })

            it('sends untracked when the consent lookup fails (fail closed)', async () => {
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'getEmailTrackingConsentMode'
                ).mockResolvedValue('opt_out')
                jest.spyOn((service as any).recipientsManager, 'get').mockRejectedValue(new Error('db down'))
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html.Data
                expect(sentHtml).toEqual(trackableHtml)
            })

            it('sends untracked when the consent-mode lookup fails (fail closed)', async () => {
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'getEmailTrackingConsentMode'
                ).mockRejectedValue(new Error('db down'))
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html.Data
                expect(sentHtml).toEqual(trackableHtml)
            })

            it('honors a cc recipient tracking opt-out for the whole send', async () => {
                invocation.queueParameters = createEmailParams({
                    from: { integrationId: 1 },
                    html: trackableHtml,
                    cc: '[email protected]',
                })
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'getEmailTrackingConsentMode'
                ).mockResolvedValue('opt_out')
                jest.spyOn((service as any).recipientsManager, 'get').mockImplementation(
                    (options: unknown): Promise<any> => {
                        const { identifier } = options as { identifier: string }
                        return Promise.resolve(
                            identifier === '[email protected]'
                                ? {
                                      id: 'pref-1',
                                      team_id: team.id,
                                      identifier,
                                      preferences: { $email_tracking: 'OPTED_OUT' },
                                      created_at: '',
                                      updated_at: '',
                                  }
                                : null
                        )
                    }
                )
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                const sentHtml = (sendEmailSpy.mock.calls[0][0] as { input: any }).input.Content.Simple.Body.Html.Data
                expect(sentHtml).toEqual(trackableHtml)
            })
        })

        it('should report a missing message id', async () => {
            sendEmailSpy.mockResolvedValue({})
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toMatchInlineSnapshot(`"Failed to send email via SES: No messageId returned from SES"`)
            expect(result.emailSendResult).toEqual({ status: 'failed', reason: result.error })
        })

        it.each([
            ['an ordinary template', {}, 'Test Subject'],
            ['a sensitive template', { sensitive: true }, undefined],
        ])(
            'should capture a $workflows_email_sent PostHog event on success, for %s',
            async (_name, extraMetadata, subject) => {
                // Engagement capture is team-opt-in; enable it for this team so the captured event is emitted.
                jest.spyOn(
                    (service as any).teamWorkflowsConfigService,
                    'shouldCaptureEngagementEvents'
                ).mockResolvedValue(true)
                invocation.hogFunction.metadata = { ...invocation.hogFunction.metadata, ...extraMetadata }
                sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
                const result = await service.executeSendEmail(invocation)
                expect(result.error).toBeUndefined()
                expect(result.capturedPostHogEvents).toHaveLength(1)
                expect(result.capturedPostHogEvents[0]).toMatchObject({
                    team_id: team.id,
                    distinct_id: 'distinct_id',
                    event: '$workflows_email_sent',
                    properties: {
                        $workflow_id: invocation.functionId,
                        $workflow_action_id: invocation.state.actionId,
                        $email_to: '[email protected]',
                        $email_tracking_enabled: true,
                    },
                })
                expect(result.capturedPostHogEvents[0].properties.$email_subject).toEqual(subject)
            }
        )

        it('does not capture a PostHog event when engagement capture is disabled for the team', async () => {
            // Default config has capture_workflows_engagement_events=false, so even on success no event is queued.
            sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeUndefined()
            expect(result.capturedPostHogEvents).toHaveLength(0)
        })

        it('should capture a $workflows_email_failed PostHog event on failure', async () => {
            jest.spyOn((service as any).teamWorkflowsConfigService, 'shouldCaptureEngagementEvents').mockResolvedValue(
                true
            )
            sendEmailSpy.mockRejectedValue(new Error('SES error'))
            const result = await service.executeSendEmail(invocation)
            expect(result.error).toBeDefined()
            expect(result.capturedPostHogEvents).toHaveLength(1)
            expect(result.capturedPostHogEvents[0]).toMatchObject({
                event: '$workflows_email_failed',
                distinct_id: 'distinct_id',
            })
        })
    })
})