Skip to content

The open alternative to Salesforce, designed for AI.

Send campaigns in batches on a paced queue (#25294)

neo77361b894ad6bb5
diff --git a/packages/twenty-front/src/modules/activities/emails/components/CampaignDetailsFields.tsx b/packages/twenty-front/src/modules/activities/emails/components/CampaignDetailsFields.tsx
index 21ada7d4760..62f8826e185 100644
--- a/packages/twenty-front/src/modules/activities/emails/components/CampaignDetailsFields.tsx
+++ b/packages/twenty-front/src/modules/activities/emails/components/CampaignDetailsFields.tsx
@@ -11,10 +11,9 @@ import { type SelectOption } from 'twenty-ui/input';
import { ThemeContext, themeCssVariables } from 'twenty-ui/theme-constants';
import {
- CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH,
CampaignEnvelopeBox,
+ CampaignEnvelopeRow,
} from '@/activities/emails/components/CampaignEnvelopeBox';
-import { ComposerFieldRow } from '@/activities/components/ComposerFieldRow';
import { useCampaignDetailsState } from '@/activities/emails/hooks/useCampaignDetailsState';
import { useUnsubscribeTopics } from '@/activities/emails/hooks/useUnsubscribeTopics';
import { type MessageCampaign } from '@/activities/emails/types/MessageCampaign';
@@ -107,10 +106,7 @@ export const CampaignDetailsFields = ({
)
}
>
- <ComposerFieldRow
- label={t`From`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`From`}>
<Select
dropdownId="campaign-composer-from-account"
fullWidth
@@ -119,11 +115,8 @@ export const CampaignDetailsFields = ({
emptyOption={{ label: t`Select a sender`, value: '' }}
onChange={detailsState.setFromAddress}
/>
- </ComposerFieldRow>
- <ComposerFieldRow
- label={t`To`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ </CampaignEnvelopeRow>
+ <CampaignEnvelopeRow label={t`To`}>
<FormSingleRecordPicker
key={`list-${detailsState.draftResyncKey}`}
objectNameSingulars={[CoreObjectNameSingular.MessageList]}
@@ -131,12 +124,9 @@ export const CampaignDetailsFields = ({
onChange={detailsState.setListId}
onCreate={handleCreateList}
/>
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
{hasTopicOptions && (
- <ComposerFieldRow
- label={t`Unsubscribe topic`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`Unsubscribe topic`}>
<Select
dropdownId="campaign-composer-unsubscribe-topic"
fullWidth
@@ -147,12 +137,9 @@ export const CampaignDetailsFields = ({
detailsState.setUnsubscribeTopicId(value === '' ? null : value)
}
/>
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
)}
- <ComposerFieldRow
- label={t`Subject`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`Subject`}>
<StyledSubjectInput
key={`subject-${detailsState.draftResyncKey}`}
type="text"
@@ -160,7 +147,7 @@ export const CampaignDetailsFields = ({
defaultValue={detailsState.subject}
onChange={(event) => detailsState.setSubject(event.target.value)}
/>
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
</CampaignEnvelopeBox>
);
};
diff --git a/packages/twenty-front/src/modules/activities/emails/components/CampaignEnvelopeBox.tsx b/packages/twenty-front/src/modules/activities/emails/components/CampaignEnvelopeBox.tsx
index 797a245a1da..bca5d75c18e 100644
--- a/packages/twenty-front/src/modules/activities/emails/components/CampaignEnvelopeBox.tsx
+++ b/packages/twenty-front/src/modules/activities/emails/components/CampaignEnvelopeBox.tsx
@@ -1,10 +1,12 @@
import { styled } from '@linaria/react';
-import { type ReactNode } from 'react';
+import { type MouseEventHandler, type ReactNode } from 'react';
import { themeCssVariables } from 'twenty-ui/theme-constants';
+import { ComposerFieldRow } from '@/activities/components/ComposerFieldRow';
+
// Widest label the campaign rows use ("Unsubscribe topic"), so every value
// starts on the same column.
-export const CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH = '116px';
+const CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH = '116px';
const StyledContainer = styled.div`
align-items: center;
@@ -58,3 +60,28 @@ export const CampaignEnvelopeBox = ({
</StyledColumn>
</StyledContainer>
);
+
+// Every envelope row shares one label width, so the draft and the sent view
+// cannot line their values up differently.
+type CampaignEnvelopeRowProps = {
+ label: string;
+ children: ReactNode;
+ trailing?: ReactNode;
+ onClick?: MouseEventHandler<HTMLDivElement>;
+};
+
+export const CampaignEnvelopeRow = ({
+ label,
+ children,
+ trailing,
+ onClick,
+}: CampaignEnvelopeRowProps) => (
+ <ComposerFieldRow
+ label={label}
+ trailing={trailing}
+ onClick={onClick}
+ labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
+ >
+ {children}
+ </ComposerFieldRow>
+);
diff --git a/packages/twenty-front/src/modules/activities/emails/components/CampaignSentEnvelope.tsx b/packages/twenty-front/src/modules/activities/emails/components/CampaignSentEnvelope.tsx
index 40d34e0d16a..603e704c400 100644
--- a/packages/twenty-front/src/modules/activities/emails/components/CampaignSentEnvelope.tsx
+++ b/packages/twenty-front/src/modules/activities/emails/components/CampaignSentEnvelope.tsx
@@ -6,10 +6,9 @@ import { isDefined, isValidUuid } from 'twenty-shared/utils';
import { themeCssVariables } from 'twenty-ui/theme-constants';
import {
- CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH,
CampaignEnvelopeBox,
+ CampaignEnvelopeRow,
} from '@/activities/emails/components/CampaignEnvelopeBox';
-import { ComposerFieldRow } from '@/activities/components/ComposerFieldRow';
import { useUnsubscribeTopics } from '@/activities/emails/hooks/useUnsubscribeTopics';
import { type MessageCampaign } from '@/activities/emails/types/MessageCampaign';
import { RecordChip } from '@/object-record/components/RecordChip';
@@ -82,20 +81,14 @@ export const CampaignSentEnvelope = ({
return (
<CampaignEnvelopeBox width={width}>
- <ComposerFieldRow
- label={t`From`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`From`}>
{isNonEmptyString(fromAddress) ? (
<StyledValue>{fromAddress}</StyledValue>
) : (
<StyledEmptyValue>{t`No sender`}</StyledEmptyValue>
)}
- </ComposerFieldRow>
- <ComposerFieldRow
- label={t`To`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ </CampaignEnvelopeRow>
+ <CampaignEnvelopeRow label={t`To`}>
{isDefined(list) ? (
<RecordChip
record={list}
@@ -108,12 +101,9 @@ export const CampaignSentEnvelope = ({
<StyledEmptyValue>{t`Unavailable`}</StyledEmptyValue>
)
)}
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
{hasUnsubscribeTopic && (
- <ComposerFieldRow
- label={t`Unsubscribe topic`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`Unsubscribe topic`}>
{isDefined(unsubscribeTopic) ? (
<StyledValue>
{unsubscribeTopic.name ?? t`Untitled topic`}
@@ -123,18 +113,15 @@ export const CampaignSentEnvelope = ({
<StyledEmptyValue>{t`Unavailable`}</StyledEmptyValue>
)
)}
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
)}
- <ComposerFieldRow
- label={t`Subject`}
- labelMinWidth={CAMPAIGN_ENVELOPE_LABEL_MIN_WIDTH}
- >
+ <CampaignEnvelopeRow label={t`Subject`}>
{isNonEmptyString(subject) ? (
<StyledValue>{subject}</StyledValue>
) : (
<StyledEmptyValue>{t`No subject`}</StyledEmptyValue>
)}
- </ComposerFieldRow>
+ </CampaignEnvelopeRow>
</CampaignEnvelopeBox>
);
};
diff --git a/packages/twenty-front/src/modules/activities/emails/hooks/useUnsubscribeTopics.ts b/packages/twenty-front/src/modules/activities/emails/hooks/useUnsubscribeTopics.ts
index 51ed5e0b21b..61bfbeaee67 100644
--- a/packages/twenty-front/src/modules/activities/emails/hooks/useUnsubscribeTopics.ts
+++ b/packages/twenty-front/src/modules/activities/emails/hooks/useUnsubscribeTopics.ts
@@ -1,9 +1,18 @@
import { useQuery } from '@apollo/client/react';
-import { UnsubscribeTopicsDocument } from '~/generated-metadata/graphql';
+import { UNSUBSCRIBE_TOPICS } from '@/activities/emails/graphql/metadata-queries/unsubscribeTopics';
+import {
+ type UnsubscribeTopicsQuery,
+ type UnsubscribeTopicsQueryVariables,
+} from '~/generated-metadata/graphql';
export const useUnsubscribeTopics = () => {
- const { data, loading } = useQuery(UnsubscribeTopicsDocument);
+ // Reads through the same document the topic mutations refetch, so a created
+ // or deleted topic refreshes this list.
+ const { data, loading } = useQuery<
+ UnsubscribeTopicsQuery,
+ UnsubscribeTopicsQueryVariables
+ >(UNSUBSCRIBE_TOPICS);
return { unsubscribeTopics: data?.unsubscribeTopics ?? [], loading };
};
diff --git a/packages/twenty-front/src/modules/command-menu-item/engine-command/record/single-record/message-campaign/components/DuplicateMessageCampaignSingleRecordCommand.tsx b/packages/twenty-front/src/modules/command-menu-item/engine-command/record/single-record/message-campaign/components/DuplicateMessageCampaignSingleRecordCommand.tsx
index de327c3bdd8..f7e2404d0e4 100644
--- a/packages/twenty-front/src/modules/command-menu-item/engine-command/record/single-record/message-campaign/components/DuplicateMessageCampaignSingleRecordCommand.tsx
+++ b/packages/twenty-front/src/modules/command-menu-item/engine-command/record/single-record/message-campaign/components/DuplicateMessageCampaignSingleRecordCommand.tsx
@@ -1,6 +1,5 @@
-import { t } from '@lingui/core/macro';
import { AppPath, CoreObjectNameSingular } from 'twenty-shared/types';
-import { isDefined } from 'twenty-shared/utils';
+import { appendCopySuffix, isDefined } from 'twenty-shared/utils';
import { v4 } from 'uuid';
import { type MessageCampaign } from '@/activities/emails/types/MessageCampaign';
@@ -48,7 +47,7 @@ export const DuplicateMessageCampaignSingleRecordCommand = () => {
await createMessageCampaign({
id: duplicatedCampaignId,
- name: t`${campaign.name} (copy)`,
+ name: appendCopySuffix(campaign.name),
subject: campaign.subject,
bodyTemplate: campaign.bodyTemplate,
fromAddress: campaign.fromAddress,
diff --git a/packages/twenty-front/src/modules/side-panel/hooks/useOpenCampaignSidePanelPage.ts b/packages/twenty-front/src/modules/side-panel/hooks/useOpenCampaignSidePanelPage.ts
new file mode 100644
index 00000000000..3f16fb0aaa0
--- /dev/null
+++ b/packages/twenty-front/src/modules/side-panel/hooks/useOpenCampaignSidePanelPage.ts
@@ -0,0 +1,49 @@
+import { useStore } from 'jotai';
+import { useCallback } from 'react';
+import { type IconComponent } from 'twenty-ui/icon';
+import { v4 } from 'uuid';
+
+import { useSidePanelMenu } from '@/side-panel/hooks/useSidePanelMenu';
+import { type PurposeBuiltSidePanelPage } from '@/side-panel/types/SidePanelPage';
+import { type sendCampaignCampaignIdComponentState } from '@/side-panel/pages/send-campaign/states/sendCampaignCampaignIdComponentState';
+
+type CampaignIdComponentState = typeof sendCampaignCampaignIdComponentState;
+
+// Both campaign panels seed their campaign id on a page instance that does not
+// exist yet, so the id has to be written against the new pageId before the
+// navigation that mounts it.
+export const useOpenCampaignSidePanelPage = ({
+ campaignIdComponentState,
+ page,
+ pageTitle,
+ pageIcon,
+}: {
+ campaignIdComponentState: CampaignIdComponentState;
+ page: PurposeBuiltSidePanelPage;
+ pageTitle: string;
+ pageIcon: IconComponent;
+}) => {
+ const store = useStore();
+ const { navigateSidePanelMenu } = useSidePanelMenu();
+
+ return useCallback(
+ (campaignId: string) => {
+ const pageId = v4();
+
+ store.set(
+ campaignIdComponentState.atomFamily({ instanceId: pageId }),
+ campaignId,
+ );
+
+ navigateSidePanelMenu({ page, pageTitle, pageIcon, pageId });
+ },
+ [
+ campaignIdComponentState,
+ navigateSidePanelMenu,
+ page,
+ pageIcon,
+ pageTitle,
+ store,
+ ],
+ );
+};
diff --git a/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignInSidePanel.ts b/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignInSidePanel.ts
index a452de3493c..af7a2938f84 100644
--- a/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignInSidePanel.ts
+++ b/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignInSidePanel.ts
@@ -1,37 +1,17 @@
-import { useStore } from 'jotai';
-import { useCallback } from 'react';
+import { t } from '@lingui/core/macro';
import { SidePanelPages } from 'twenty-shared/types';
import { IconSend } from 'twenty-ui/icon';
-import { v4 } from 'uuid';
-import { useSidePanelMenu } from '@/side-panel/hooks/useSidePanelMenu';
+import { useOpenCampaignSidePanelPage } from '@/side-panel/hooks/useOpenCampaignSidePanelPage';
import { sendCampaignCampaignIdComponentState } from '@/side-panel/pages/send-campaign/states/sendCampaignCampaignIdComponentState';
-import { t } from '@lingui/core/macro';
export const useOpenSendCampaignInSidePanel = () => {
- const store = useStore();
- const { navigateSidePanelMenu } = useSidePanelMenu();
-
- const openSendCampaignInSidePanel = useCallback(
- (campaignId: string) => {
- const pageId = v4();
-
- store.set(
- sendCampaignCampaignIdComponentState.atomFamily({
- instanceId: pageId,
- }),
- campaignId,
- );
-
- navigateSidePanelMenu({
- page: SidePanelPages.SendCampaign,
- pageTitle: t`Send Campaign`,
- pageIcon: IconSend,
- pageId,
- });
- },
- [navigateSidePanelMenu, store],
- );
+ const openSendCampaignInSidePanel = useOpenCampaignSidePanelPage({
+ campaignIdComponentState: sendCampaignCampaignIdComponentState,
+ page: SidePanelPages.SendCampaign,
+ pageTitle: t`Send Campaign`,
+ pageIcon: IconSend,
+ });
return { openSendCampaignInSidePanel };
};
diff --git a/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignTestInSidePanel.ts b/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignTestInSidePanel.ts
index 41d8a5bfa7a..9943a56cee4 100644
--- a/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignTestInSidePanel.ts
+++ b/packages/twenty-front/src/modules/side-panel/hooks/useOpenSendCampaignTestInSidePanel.ts
@@ -1,37 +1,17 @@
-import { useStore } from 'jotai';
-import { useCallback } from 'react';
+import { t } from '@lingui/core/macro';
import { SidePanelPages } from 'twenty-shared/types';
import { IconMail } from 'twenty-ui/icon';
-import { v4 } from 'uuid';
-import { useSidePanelMenu } from '@/side-panel/hooks/useSidePanelMenu';
+import { useOpenCampaignSidePanelPage } from '@/side-panel/hooks/useOpenCampaignSidePanelPage';
import { sendCampaignTestCampaignIdComponentState } from '@/side-panel/pages/send-campaign-test/states/sendCampaignTestCampaignIdComponentState';
-import { t } from '@lingui/core/macro';
export const useOpenSendCampaignTestInSidePanel = () => {
- const store = useStore();
- const { navigateSidePanelMenu } = useSidePanelMenu();
-
- const openSendCampaignTestInSidePanel = useCallback(
- (campaignId: string) => {
- const pageId = v4();
-
- store.set(
- sendCampaignTestCampaignIdComponentState.atomFamily({
- instanceId: pageId,
- }),
- campaignId,
- );
-
- navigateSidePanelMenu({
- page: SidePanelPages.SendCampaignTest,
- pageTitle: t`Send Test Email`,
- pageIcon: IconMail,
- pageId,
- });
- },
- [navigateSidePanelMenu, store],
- );
+ const openSendCampaignTestInSidePanel = useOpenCampaignSidePanelPage({
+ campaignIdComponentState: sendCampaignTestCampaignIdComponentState,
+ page: SidePanelPages.SendCampaignTest,
+ pageTitle: t`Send Test Email`,
+ pageIcon: IconMail,
+ });
return { openSendCampaignTestInSidePanel };
};
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-instance-command-fast-1788767400000-add-campaign-delivery-claim-token-index.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-instance-command-fast-1788767400000-add-campaign-delivery-claim-token-index.ts
new file mode 100644
index 00000000000..b7388d94ae8
--- /dev/null
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/2-39/2-39-instance-command-fast-1788767400000-add-campaign-delivery-claim-token-index.ts
@@ -0,0 +1,25 @@
+import { type QueryRunner } from 'typeorm';
+
+import { RegisteredInstanceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-instance-command.decorator';
+import { type FastInstanceCommand } from 'src/engine/core-modules/upgrade/interfaces/fast-instance-command.interface';
+
+// Every batch send job releases its unsent claims in a finally block, filtering
+// on workspaceId and claimToken alone. Without this index that is a sequential
+// scan of the whole cross-tenant table once per batch. Partial, so it only
+// covers the rows still holding a claim.
+@RegisteredInstanceCommand('2.39.0', 1788767400000)
+export class AddCampaignDeliveryClaimTokenIndexFastInstanceCommand
+ implements FastInstanceCommand
+{
+ public async up(queryRunner: QueryRunner): Promise<void> {
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_CAMPAIGN_DELIVERY_CLAIM_TOKEN" ON "core"."campaignDelivery" ("workspaceId", "claimToken") WHERE "claimToken" IS NOT NULL`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise<void> {
+ await queryRunner.query(
+ `DROP INDEX IF EXISTS "core"."IDX_CAMPAIGN_DELIVERY_CLAIM_TOKEN"`,
+ );
+ }
+}
diff --git a/packages/twenty-server/src/database/commands/upgrade-version-command/instance-commands.constant.ts b/packages/twenty-server/src/database/commands/upgrade-version-command/instance-commands.constant.ts
index 411aab4fec4..9284ed6073c 100644
--- a/packages/twenty-server/src/database/commands/upgrade-version-command/instance-commands.constant.ts
+++ b/packages/twenty-server/src/database/commands/upgrade-version-command/instance-commands.constant.ts
@@ -162,6 +162,7 @@ import { AddUsageLimitFastInstanceCommand } from 'src/database/commands/upgrade-
import { MakeUserEmailCaseInsensitiveFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-37/2-37-instance-command-fast-1787836741000-make-user-email-case-insensitive';
import { BackfillMissingPageLayoutWidgetPositionsSlowInstanceCommand } from 'src/database/commands/upgrade-version-command/2-37/2-37-instance-command-slow-1787838153752-backfill-missing-page-layout-widget-positions';
import { AddCommandMenuItemConditionalPinnedExpressionFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-39/2-39-instance-command-fast-1788701640813-add-command-menu-item-conditional-pinned-expression';
+import { AddCampaignDeliveryClaimTokenIndexFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-39/2-39-instance-command-fast-1788767400000-add-campaign-delivery-claim-token-index';
import { AddBillingToApplicationFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-38/2-38-instance-command-fast-1788340843000-add-billing-to-application';
import { AddPricingDescriptionToApplicationRegistrationFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-38/2-38-instance-command-fast-1788340844000-add-pricing-description-to-application-registration';
import { AddRecordFormPageLayoutAndFormFieldWidgetFastInstanceCommand } from 'src/database/commands/upgrade-version-command/2-38/2-38-instance-command-fast-1787920209300-add-record-form-page-layout-and-form-field-widget';
@@ -356,4 +357,5 @@ export const INSTANCE_COMMANDS = [
AddLogoToConnectionProviderFastInstanceCommand,
AddReadabilityToObjectMetadataFastInstanceCommand,
AddCommandMenuItemConditionalPinnedExpressionFastInstanceCommand,
+ AddCampaignDeliveryClaimTokenIndexFastInstanceCommand,
];
diff --git a/packages/twenty-server/src/engine/core-modules/admin-panel/__tests__/worker.health.spec.ts b/packages/twenty-server/src/engine/core-modules/admin-panel/__tests__/worker.health.spec.ts
index 28b62f38930..0d909bb5c65 100644
--- a/packages/twenty-server/src/engine/core-modules/admin-panel/__tests__/worker.health.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/admin-panel/__tests__/worker.health.spec.ts
@@ -22,6 +22,9 @@ jest.mock('bullmq', () => ({
Queue: jest.fn(() => mockQueueInstance),
}));
+const drainWorkerChecksLeftRunningByTheTimeout = () =>
+ new Promise((resolve) => setImmediate(resolve));
+
describe('WorkerHealthIndicator', () => {
let service: WorkerHealthIndicator;
let mockRedis: jest.Mocked<Pick<Redis, 'ping'>>;
@@ -130,6 +133,8 @@ describe('WorkerHealthIndicator', () => {
expect(result.worker.error).toBe(HEALTH_ERROR_MESSAGES.WORKER_TIMEOUT);
}
jest.useRealTimers();
+
+ await drainWorkerChecksLeftRunningByTheTimeout();
});
it('should check all message queues', async () => {
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/campaign-delivery.entity.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/campaign-delivery.entity.ts
index 0a8090d95da..dd06e34c0cb 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/campaign-delivery.entity.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/campaign-delivery.entity.ts
@@ -32,6 +32,9 @@ import { WorkspaceRelatedEntity } from 'src/engine/workspace-manager/types/works
where: `"state" = 'SENDING'`,
})
@Index('IDX_CAMPAIGN_DELIVERY_COUNTS', ['workspaceId', 'campaignId', 'state'])
+@Index('IDX_CAMPAIGN_DELIVERY_CLAIM_TOKEN', ['workspaceId', 'claimToken'], {
+ where: '"claimToken" IS NOT NULL',
+})
@Index(
'IDX_CAMPAIGN_DELIVERY_PROVIDER_MESSAGE_ID',
['workspaceId', 'providerMessageId'],
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant.ts
index f3d327c12e8..85fd534dc7d 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant.ts
@@ -7,6 +7,11 @@ export const CAMPAIGN_FAILURE_REASON = {
UNSUBSCRIBE_NOT_READY: 'UNSUBSCRIBE_NOT_READY',
UNSUBSCRIBE_MULTIPLE_RECIPIENTS: 'UNSUBSCRIBE_MULTIPLE_RECIPIENTS',
CLAIM_EXPIRED: 'CLAIM_EXPIRED',
+ // The provider accepted the batch but settling it threw, so the rows are
+ // sent without a provider id rather than re-sendable.
+ SETTLEMENT_LOST: 'SETTLEMENT_LOST',
+ // Queued with no send job left to pick it up, found by the stale cron.
+ ORPHANED: 'ORPHANED',
RATE_LIMITED: 'RATE_LIMITED',
UNKNOWN: 'UNKNOWN',
} as const;
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-send-batch-size.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-send-batch-size.constant.ts
new file mode 100644
index 00000000000..729f022f79d
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/campaign-send-batch-size.constant.ts
@@ -0,0 +1 @@
+export const CAMPAIGN_SEND_BATCH_SIZE = 50;
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant.ts
new file mode 100644
index 00000000000..bb71bc2ec98
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant.ts
@@ -0,0 +1 @@
+export const SEND_CAMPAIGN_EMAIL_BATCH_JOB = 'SendCampaignEmailBatchJob';
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant.ts
new file mode 100644
index 00000000000..9a21bd73bf8
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant.ts
@@ -0,0 +1,7 @@
+export const SEND_SLOT_RETRY = {
+ attemptLimit: 60,
+ jitterRatio: 0.5,
+ maxWindows: 3,
+ minDelayMs: 1_000,
+ maxDelayMs: 60_000,
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/constants/ses-bulk-max-destinations.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/constants/ses-bulk-max-destinations.constant.ts
new file mode 100644
index 00000000000..7fc3c0954e4
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/constants/ses-bulk-max-destinations.constant.ts
@@ -0,0 +1 @@
+export const SES_BULK_MAX_DESTINATIONS = 50;
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-driver.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-driver.service.ts
index 9188a6e23cb..94367e5acc6 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-driver.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-driver.service.ts
@@ -20,6 +20,8 @@ import {
type EmailingDomainResourceInput,
type EmailingDomainVerificationResult,
} from 'src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface';
+import { type EmailingDomainSendEmailBatchRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type';
+import { type EmailingDomainSendEmailBatchResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type';
import { type EmailingDomainSendEmailRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
import { getUnsubscribeBaseUrl } from 'src/engine/core-modules/emailing-domain/drivers/utils/get-unsubscribe-base-url.util';
@@ -166,6 +168,21 @@ export class AwsSesDriver implements EmailingDomainDriverInterface {
});
}
+ async sendEmailBatch(
+ input: EmailingDomainSendEmailBatchRequest,
+ ): Promise<EmailingDomainSendEmailBatchResult> {
+ const unsubscribeBaseUrl = getUnsubscribeBaseUrl(input.emailingDomain);
+ const batchToSend = this.unsubscribeContentService.addToBatch(
+ input,
+ unsubscribeBaseUrl,
+ );
+
+ return this.awsSesSendEmailService.sendEmailBatch(batchToSend, {
+ tenantName: this.buildTenantName(input.workspaceId),
+ configurationSetName: this.buildConfigurationSetName(input.workspaceId),
+ });
+ }
+
async cleanupDomain(input: EmailingDomainResourceInput): Promise<void> {
const sesClient = this.awsSesClientProvider.getSESClient();
const tenantName = this.buildTenantName(input.workspaceId);
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-send-email.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-send-email.service.ts
index 1353b517001..8fb3759f081 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-send-email.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-send-email.service.ts
@@ -1,11 +1,14 @@
import { Injectable, Logger } from '@nestjs/common';
-import { SendEmailCommand } from '@aws-sdk/client-sesv2';
+import { SendBulkEmailCommand, SendEmailCommand } from '@aws-sdk/client-sesv2';
import { isDefined, isNonEmptyArray } from 'twenty-shared/utils';
+import { type EmailingDomainSendEmailBatchInput } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type';
+import { type EmailingDomainSendEmailBatchResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type';
import { type EmailingDomainSendEmailInput } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
+import { SES_BULK_MAX_DESTINATIONS } from 'src/engine/core-modules/emailing-domain/drivers/aws-ses/constants/ses-bulk-max-destinations.constant';
import { AwsSesClientProvider } from 'src/engine/core-modules/emailing-domain/drivers/aws-ses/providers/aws-ses-client.provider';
import { AwsSesHandleErrorService } from 'src/engine/core-modules/emailing-domain/drivers/aws-ses/services/aws-ses-handle-error.service';
import {
@@ -111,4 +114,101 @@ export class AwsSesSendEmailService {
this.awsSesHandleErrorService.handleAwsSesError(error, 'sendEmail');
}
}
+ async sendEmailBatch(
+ input: EmailingDomainSendEmailBatchInput,
+ context: SendEmailContext,
+ ): Promise<EmailingDomainSendEmailBatchResult> {
+ if (!isNonEmptyArray(input.recipients)) {
+ throw new EmailingDomainDriverException(
+ 'sendEmailBatch requires at least one recipient',
+ EmailingDomainDriverExceptionCode.CONFIGURATION_ERROR,
+ );
+ }
+
+ if (input.recipients.length > SES_BULK_MAX_DESTINATIONS) {
+ throw new EmailingDomainDriverException(
+ `sendEmailBatch accepts at most ${SES_BULK_MAX_DESTINATIONS} recipients, received ${input.recipients.length}`,
+ EmailingDomainDriverExceptionCode.CONFIGURATION_ERROR,
+ );
+ }
+
+ try {
+ const sesClient = this.awsSesClientProvider.getSESClient();
+
+ const response = await sesClient.send(
+ new SendBulkEmailCommand({
+ FromEmailAddress: input.from,
+ ReplyToAddresses: input.replyTo,
+ DefaultContent: {
+ Template: {
+ TemplateContent: {
+ Subject: input.template.subject,
+ Text: input.template.text,
+ Html: input.template.html,
+ },
+ TemplateData: '{}',
+ },
+ },
+ BulkEmailEntries: input.recipients.map((recipient) => ({
+ Destination: { ToAddresses: [recipient.email] },
+ ReplacementEmailContent: {
+ ReplacementTemplate: {
+ ReplacementTemplateData: JSON.stringify(recipient.replacements),
+ },
+ },
+ ReplacementHeaders: isNonEmptyArray(recipient.headers)
+ ? recipient.headers.map((header) => ({
+ Name: header.name,
+ Value: header.value,
+ }))
+ : undefined,
+ })),
+ ConfigurationSetName: context.configurationSetName,
+ TenantName: context.tenantName,
+ DefaultEmailTags: [
+ { Name: 'workspace', Value: input.workspaceId },
+ { Name: 'domain', Value: input.domain },
+ { Name: 'tenant_id', Value: input.workspaceId },
+ ],
+ }),
+ );
+
+ const results = response.BulkEmailEntryResults ?? [];
+
+ return {
+ entries: input.recipients.map((_recipient, index) => {
+ const result = results[index];
+
+ if (!isDefined(result)) {
+ return {
+ recipientIndex: index,
+ messageId: null,
+ errorMessage: 'SES returned no result for this destination',
+ };
+ }
+
+ if (!isDefined(result.MessageId)) {
+ return {
+ recipientIndex: index,
+ messageId: null,
+ errorMessage:
+ result.Error ??
+ `SES rejected the destination (${result.Status})`,
+ };
+ }
+
+ return {
+ recipientIndex: index,
+ messageId: result.MessageId,
+ errorMessage: null,
+ };
+ }),
+ };
+ } catch (error) {
+ if (error instanceof EmailingDomainDriverException) {
+ throw error;
+ }
+ this.awsSesHandleErrorService.handleAwsSesError(error, 'sendEmailBatch');
+ }
+ }
}
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface.ts
index 632d28d6479..7645d246270 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface.ts
@@ -1,3 +1,5 @@
+import { type EmailingDomainSendEmailBatchRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type';
+import { type EmailingDomainSendEmailBatchResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type';
import { type EmailingDomainSendEmailRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
import { type EmailingDomainStatus } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-status.type';
@@ -27,4 +29,7 @@ export interface EmailingDomainDriverInterface {
sendEmail(
input: EmailingDomainSendEmailRequest,
): Promise<EmailingDomainSendEmailResult>;
+ sendEmailBatch(
+ input: EmailingDomainSendEmailBatchRequest,
+ ): Promise<EmailingDomainSendEmailBatchResult>;
}
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/log/services/log-emailing-domain-driver.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/log/services/log-emailing-domain-driver.service.ts
index e1c2e17c43f..248d7879922 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/log/services/log-emailing-domain-driver.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/log/services/log-emailing-domain-driver.service.ts
@@ -16,6 +16,9 @@ import {
type EmailingDomainVerificationResult,
} from 'src/engine/core-modules/emailing-domain/drivers/interfaces/emailing-domain-driver.interface';
import { EmailingDomainStatus } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-status.type';
+import { type EmailingDomainSendEmailBatchRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type';
+import { type EmailingDomainSendEmailBatchResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type';
+import { applyReplacementTags } from 'src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util';
import { type EmailingDomainSendEmailRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
import { UnsubscribeContentService } from 'src/engine/core-modules/emailing-domain/services/unsubscribe-content.service';
@@ -166,6 +169,47 @@ export class LogEmailingDomainDriver implements EmailingDomainDriverInterface {
};
}
+ async sendEmailBatch(
+ input: EmailingDomainSendEmailBatchRequest,
+ ): Promise<EmailingDomainSendEmailBatchResult> {
+ await this.simulateProviderCall();
+
+ const unsubscribeBaseUrl = await this.getUnsubscribeBaseUrl(
+ input.workspaceId,
+ );
+ const batchToSend = this.unsubscribeContentService.addToBatch(
+ input,
+ unsubscribeBaseUrl,
+ );
+
+ this.logger.log(
+ `[log-driver] sendEmailBatch → ${batchToSend.recipients.length} destination(s) from ${batchToSend.from}`,
+ );
+
+ return {
+ entries: batchToSend.recipients.map((recipient, index) => {
+ const messageId = `log-${v4()}`;
+
+ this.logger.log(
+ `[log-driver] batch entry → fake messageId=${messageId}\n` +
+ `To: ${recipient.email}\n` +
+ `Subject: ${applyReplacementTags(batchToSend.template.subject, recipient.replacements)}\n` +
+ `Content Text: ${applyReplacementTags(batchToSend.template.text, recipient.replacements)}\n` +
+ `Content HTML: ${
+ isNonEmptyString(batchToSend.template.html)
+ ? applyReplacementTags(
+ batchToSend.template.html,
+ recipient.replacements,
+ )
+ : '(none)'
+ }`,
+ );
+
+ return { recipientIndex: index, messageId, errorMessage: null };
+ }),
+ };
+ }
+
private async getUnsubscribeBaseUrl(
workspaceId: string,
): Promise<string | null> {
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-api-client.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-api-client.service.ts
index 498084d1593..cbeaa93c543 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-api-client.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-api-client.service.ts
@@ -23,6 +23,16 @@ export class ResendApiClientService {
return this.requestJson<{ id: string }>('POST', '/emails', payload);
}
+ async sendEmailBatch(
+ payloads: ResendSendEmailPayload[],
+ ): Promise<{ data: { id: string }[] }> {
+ return this.requestJson<{ data: { id: string }[] }>(
+ 'POST',
+ '/emails/batch',
+ payloads,
+ );
+ }
+
async createDomain(payload: {
name: string;
region?: string;
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-driver.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-driver.service.ts
index 6cecf7f98f5..ce99c17bcaa 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-driver.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/resend/services/resend-driver.service.ts
@@ -20,11 +20,16 @@ import { mapResendDomainRecords } from 'src/engine/core-modules/emailing-domain/
import { mapResendSendingStatus } from 'src/engine/core-modules/emailing-domain/drivers/resend/utils/map-resend-sending-status.util';
import { RESEND_WORKSPACE_TAG_NAME } from 'src/engine/core-modules/emailing-domain/drivers/resend/constants/resend-workspace-tag-name.constant';
import { EmailingDomainStatus } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-status.type';
+import { type EmailingDomainSendEmailBatchRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type';
+import { type EmailingDomainSendEmailBatchResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type';
+import { applyReplacementTags } from 'src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util';
import { type EmailingDomainSendEmailRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
import { getUnsubscribeBaseUrl } from 'src/engine/core-modules/emailing-domain/drivers/utils/get-unsubscribe-base-url.util';
import { type UnsubscribeContentService } from 'src/engine/core-modules/emailing-domain/services/unsubscribe-content.service';
+const RESEND_BATCH_MAX_EMAILS = 100;
+
export class ResendDriver implements EmailingDomainDriverInterface {
private readonly logger = new Logger(ResendDriver.name);
@@ -167,6 +172,76 @@ export class ResendDriver implements EmailingDomainDriverInterface {
};
}
+ async sendEmailBatch(
+ input: EmailingDomainSendEmailBatchRequest,
+ ): Promise<EmailingDomainSendEmailBatchResult> {
+ if (!isNonEmptyArray(input.recipients)) {
+ throw new EmailingDomainDriverException(
+ 'sendEmailBatch requires at least one recipient',
+ EmailingDomainDriverExceptionCode.CONFIGURATION_ERROR,
+ );
+ }
+
+ if (input.recipients.length > RESEND_BATCH_MAX_EMAILS) {
+ throw new EmailingDomainDriverException(
+ `sendEmailBatch accepts at most ${RESEND_BATCH_MAX_EMAILS} recipients, received ${input.recipients.length}`,
+ EmailingDomainDriverExceptionCode.CONFIGURATION_ERROR,
+ );
+ }
+
+ const unsubscribeBaseUrl = getUnsubscribeBaseUrl(input.emailingDomain);
+ const batchToSend = this.unsubscribeContentService.addToBatch(
+ input,
+ unsubscribeBaseUrl,
+ );
+
+ const payloads: ResendSendEmailPayload[] = batchToSend.recipients.map(
+ (recipient) => ({
+ from: batchToSend.from,
+ to: [recipient.email],
+ reply_to: batchToSend.replyTo,
+ subject: applyReplacementTags(
+ batchToSend.template.subject,
+ recipient.replacements,
+ ),
+ text: applyReplacementTags(
+ batchToSend.template.text,
+ recipient.replacements,
+ ),
+ html: isNonEmptyString(batchToSend.template.html)
+ ? applyReplacementTags(
+ batchToSend.template.html,
+ recipient.replacements,
+ )
+ : undefined,
+ headers: isNonEmptyArray(recipient.headers)
+ ? Object.fromEntries(
+ recipient.headers.map((header) => [header.name, header.value]),
+ )
+ : undefined,
+ tags: [
+ { name: RESEND_WORKSPACE_TAG_NAME, value: batchToSend.workspaceId },
+ ],
+ }),
+ );
+
+ const { data } = await this.resendApiClientService.sendEmailBatch(payloads);
+
+ return {
+ entries: batchToSend.recipients.map((_recipient, index) => {
+ const id = data?.[index]?.id;
+
+ return isNonEmptyString(id)
+ ? { recipientIndex: index, messageId: id, errorMessage: null }
+ : {
+ recipientIndex: index,
+ messageId: null,
+ errorMessage: 'Resend returned no id for this destination',
+ };
+ }),
+ };
+ }
+
private async findOrCreateDomain(domainName: string): Promise<ResendDomain> {
const existingDomain = await this.findDomainByName(domainName);
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-batch-recipient.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-batch-recipient.type.ts
new file mode 100644
index 00000000000..fb9e3aa6b6b
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-batch-recipient.type.ts
@@ -0,0 +1,7 @@
+import { type EmailingDomainHeader } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-header.type';
+
+export type EmailingDomainBatchRecipient = {
+ email: string;
+ replacements: Record<string, string>;
+ headers?: EmailingDomainHeader[];
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type.ts
new file mode 100644
index 00000000000..432a7b86cf6
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type.ts
@@ -0,0 +1,5 @@
+export type EmailingDomainEmailTemplate = {
+ subject: string;
+ text: string;
+ html?: string;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type.ts
new file mode 100644
index 00000000000..5b70571c257
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type.ts
@@ -0,0 +1,14 @@
+import { type EmailingDomainBatchRecipient } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-batch-recipient.type';
+import { type EmailingDomainEmailTemplate } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type';
+import { type EmailingDomainSendKind } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-kind.type';
+
+export type EmailingDomainSendEmailBatchInput = {
+ sendKind: EmailingDomainSendKind;
+ workspaceId: string;
+ domain: string;
+ from: string;
+ replyTo?: string[];
+ template: EmailingDomainEmailTemplate;
+ recipients: EmailingDomainBatchRecipient[];
+ unsubscribeTopicId?: string;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type.ts
new file mode 100644
index 00000000000..f81af7508a6
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-request.type.ts
@@ -0,0 +1,7 @@
+import { type EmailingDomainSendEmailBatchInput } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type';
+import { type EmailingDomainEntity } from 'src/engine/core-modules/emailing-domain/emailing-domain.entity';
+
+export type EmailingDomainSendEmailBatchRequest =
+ EmailingDomainSendEmailBatchInput & {
+ emailingDomain: EmailingDomainEntity;
+ };
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type.ts
new file mode 100644
index 00000000000..25cb89209ad
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-result.type.ts
@@ -0,0 +1,11 @@
+export type EmailingDomainSendEmailBatchResult = {
+ // Index into the recipients the driver was handed. Drivers already build
+ // their results by walking that array, so reporting the position keeps a
+ // result attached to its recipient without the caller re-deriving it from
+ // the address, which two recipients can share.
+ entries: {
+ recipientIndex: number;
+ messageId: string | null;
+ errorMessage: string | null;
+ }[];
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/services/unsubscribe-content.service.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/services/unsubscribe-content.service.ts
index 4b3b3500555..ac2cf81c5af 100644
--- a/packages/twenty-server/src/engine/core-modules/emailing-domain/services/unsubscribe-content.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/services/unsubscribe-content.service.ts
@@ -6,7 +6,9 @@ import {
EmailingDomainDriverException,
EmailingDomainDriverExceptionCode,
} from 'src/engine/core-modules/emailing-domain/drivers/exceptions/emailing-domain-driver.exception';
+import { type EmailingDomainSendEmailBatchInput } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-batch-input.type';
import { type EmailingDomainSendEmailInput } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
+import { escapeHtml } from 'src/engine/core-modules/emailing-domain/utils/escape-html.util';
import { getSoleEnvelopeRecipient } from 'src/engine/core-modules/emailing-domain/utils/get-sole-envelope-recipient.util';
import { UnsubscribeTokenService } from 'src/engine/core-modules/emailing-domain/services/unsubscribe-token.service';
import { buildUnsubscribeHeaders } from 'src/engine/core-modules/emailing-domain/utils/build-unsubscribe-headers.util';
@@ -15,6 +17,11 @@ import { buildUnsubscribeHtmlFooter } from 'src/engine/core-modules/emailing-dom
import { buildUnsubscribeTextFooter } from 'src/engine/core-modules/emailing-domain/utils/build-unsubscribe-text-footer.util';
import { buildUnsubscribeWebUrl } from 'src/engine/core-modules/emailing-domain/utils/build-unsubscribe-web-url.util';
+const UNSUBSCRIBE_URL_REPLACEMENT_TAGS = {
+ html: 'v_url_unsubscribe_html',
+ text: 'v_url_unsubscribe_text',
+};
+
@Injectable()
export class UnsubscribeContentService {
constructor(
@@ -67,4 +74,59 @@ export class UnsubscribeContentService {
],
};
}
+
+ addToBatch(
+ batch: EmailingDomainSendEmailBatchInput,
+ unsubscribeBaseUrl: string | null,
+ ): EmailingDomainSendEmailBatchInput {
+ if (batch.sendKind === 'TRANSACTIONAL') {
+ return batch;
+ }
+
+ if (!isNonEmptyString(unsubscribeBaseUrl)) {
+ throw new EmailingDomainDriverException(
+ 'A marketing email cannot be sent before the unsubscribe domain is active, because it would ship with no way to unsubscribe',
+ EmailingDomainDriverExceptionCode.UNSUBSCRIBE_NOT_READY,
+ );
+ }
+
+ const htmlUrlTag = `{{${UNSUBSCRIBE_URL_REPLACEMENT_TAGS.html}}}`;
+ const textUrlTag = `{{${UNSUBSCRIBE_URL_REPLACEMENT_TAGS.text}}}`;
+
+ return {
+ ...batch,
+ template: {
+ ...batch.template,
+ text: `${batch.template.text}${buildUnsubscribeTextFooter(textUrlTag)}`,
+ html: isNonEmptyString(batch.template.html)
+ ? appendHtmlFooter(
+ batch.template.html,
+ buildUnsubscribeHtmlFooter(htmlUrlTag),
+ )
+ : batch.template.html,
+ },
+ recipients: batch.recipients.map((recipient) => {
+ const webUrl = buildUnsubscribeWebUrl({
+ unsubscribeBaseUrl,
+ token: this.unsubscribeTokenService.sign({
+ workspaceId: batch.workspaceId,
+ emailAddress: recipient.email,
+ }),
+ });
+
+ return {
+ ...recipient,
+ replacements: {
+ ...recipient.replacements,
+ [UNSUBSCRIBE_URL_REPLACEMENT_TAGS.html]: escapeHtml(webUrl),
+ [UNSUBSCRIBE_URL_REPLACEMENT_TAGS.text]: webUrl,
+ },
+ headers: [
+ ...(recipient.headers ?? []),
+ ...buildUnsubscribeHeaders({ webUrl }),
+ ],
+ };
+ }),
+ };
+ }
}
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type.ts
new file mode 100644
index 00000000000..11dd1ebd988
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type.ts
@@ -0,0 +1,8 @@
+export type SendCampaignEmailBatchJobData = {
+ workspaceId: string;
+ campaignId: string;
+ emailingDomainId: string;
+ userWorkspaceId: string;
+ recipients: { messageId: string; personId: string; email: string }[];
+ rateLimitedAttemptCount?: number;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-slot-refusal.type.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-slot-refusal.type.ts
new file mode 100644
index 00000000000..e70507a9103
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/types/send-slot-refusal.type.ts
@@ -0,0 +1,7 @@
+export type SendSlotRefusal = {
+ retryDelayMs: number;
+ windowMs: number;
+ // What the workspace is actually allowed per window. A batch costing more
+ // than this can never be admitted at its current size, however long it waits.
+ limitValue: number | null;
+};
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/__tests__/resolve-campaign-send-batch-size.util.spec.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/__tests__/resolve-campaign-send-batch-size.util.spec.ts
new file mode 100644
index 00000000000..d1a097fa853
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/__tests__/resolve-campaign-send-batch-size.util.spec.ts
@@ -0,0 +1,50 @@
+import { CAMPAIGN_SEND_BATCH_SIZE } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-batch-size.constant';
+import { resolveCampaignSendBatchSize } from 'src/engine/core-modules/emailing-domain/utils/resolve-campaign-send-batch-size.util';
+
+const computeMessagesPerWindow = (configuredEmailSendRateLimit: number) => {
+ const batchSize = resolveCampaignSendBatchSize(configuredEmailSendRateLimit);
+
+ return batchSize * Math.floor(configuredEmailSendRateLimit / batchSize);
+};
+
+describe('resolveCampaignSendBatchSize', () => {
+ it('should cap the batch at the provider ceiling when the limit is higher', () => {
+ expect(resolveCampaignSendBatchSize(100)).toBe(CAMPAIGN_SEND_BATCH_SIZE);
+ });
+
+ it('should use the ceiling when the limit equals it', () => {
+ expect(resolveCampaignSendBatchSize(CAMPAIGN_SEND_BATCH_SIZE)).toBe(
+ CAMPAIGN_SEND_BATCH_SIZE,
+ );
+ });
+
+ it('should shrink the batch to the limit when the limit is below the ceiling', () => {
+ expect(resolveCampaignSendBatchSize(10)).toBe(10);
+ });
+
+ it('should send one message per batch when the limit is one', () => {
+ expect(resolveCampaignSendBatchSize(1)).toBe(1);
+ });
+
+ it('should still return a sendable batch size when the limit is zero', () => {
+ expect(resolveCampaignSendBatchSize(0)).toBe(1);
+ });
+
+ it('should never let a window carry more messages than the configured limit', () => {
+ for (const configuredEmailSendRateLimit of [
+ 1, 2, 10, 49, 50, 75, 100, 500,
+ ]) {
+ expect(
+ computeMessagesPerWindow(configuredEmailSendRateLimit),
+ ).toBeLessThanOrEqual(configuredEmailSendRateLimit);
+ }
+ });
+
+ it('should let the default configuration send its full budget per window', () => {
+ expect(computeMessagesPerWindow(100)).toBe(100);
+ });
+
+ it('should send exactly the configured budget when the limit is below the ceiling', () => {
+ expect(computeMessagesPerWindow(10)).toBe(10);
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util.ts
new file mode 100644
index 00000000000..ed7e8f1b29c
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util.ts
@@ -0,0 +1,11 @@
+const REPLACEMENT_TAG_PATTERN = /\{\{([a-zA-Z0-9_]+)\}\}/g;
+
+export const applyReplacementTags = (
+ template: string,
+ replacements: Record<string, string>,
+): string =>
+ template.replace(REPLACEMENT_TAG_PATTERN, (match, tagName) =>
+ Object.prototype.hasOwnProperty.call(replacements, tagName)
+ ? replacements[tagName]
+ : match,
+ );
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/resolve-campaign-send-batch-size.util.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/resolve-campaign-send-batch-size.util.ts
new file mode 100644
index 00000000000..72c04fa52d5
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/utils/resolve-campaign-send-batch-size.util.ts
@@ -0,0 +1,13 @@
+import { CAMPAIGN_SEND_BATCH_SIZE } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-batch-size.constant';
+
+const SMALLEST_SENDABLE_BATCH_SIZE = 1;
+
+export const resolveCampaignSendBatchSize = (
+ configuredEmailSendRateLimit: number,
+): number =>
+ Math.max(
+ SMALLEST_SENDABLE_BATCH_SIZE,
+ Math.floor(
+ Math.min(CAMPAIGN_SEND_BATCH_SIZE, configuredEmailSendRateLimit),
+ ),
+ );
diff --git a/packages/twenty-server/src/engine/core-modules/message-queue/jobs.module.ts b/packages/twenty-server/src/engine/core-modules/message-queue/jobs.module.ts
index 425cbc80fca..9f98863050f 100644
--- a/packages/twenty-server/src/engine/core-modules/message-queue/jobs.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/message-queue/jobs.module.ts
@@ -30,6 +30,7 @@ import { MaterializeCampaignChunkJob } from 'src/modules/emailing/jobs/materiali
import { MaterializeCampaignJob } from 'src/modules/emailing/jobs/materialize-campaign.job';
import { ReconcileWorkspaceCampaignStatsJob } from 'src/modules/emailing/jobs/reconcile-workspace-campaign-stats.job';
import { RefreshCampaignStatsJob } from 'src/modules/emailing/jobs/refresh-campaign-stats.job';
+import { SendCampaignEmailBatchJob } from 'src/modules/emailing/jobs/send-campaign-email-batch.job';
import { SendCampaignEmailJob } from 'src/modules/emailing/jobs/send-campaign-email.job';
import { EnterpriseModule } from 'src/engine/core-modules/enterprise/enterprise.module';
import { EventLogIngestionModule } from 'src/engine/core-modules/event-logs/ingest/event-log-ingestion.module';
@@ -116,6 +117,7 @@ import { WorkflowModule } from 'src/modules/workflow/workflow.module';
CleanOnboardingWorkspacesJob,
EmailSenderJob,
SendCampaignEmailJob,
+ SendCampaignEmailBatchJob,
MaterializeCampaignJob,
MaterializeCampaignChunkJob,
RefreshCampaignStatsJob,
diff --git a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts
index c866ecceb5b..231d0e25e84 100644
--- a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts
+++ b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts
@@ -76,6 +76,15 @@ export const MESSAGE_QUEUE_WORKER_CONFIG: Record<
boundedShutdownDrain: false,
},
},
+ [MessageQueue.campaignSendQueue]: {
+ priority: 6,
+ workerOptions: {
+ concurrency: 10,
+ lockDuration: 30_000,
+ maxStalledCount: 1,
+ boundedShutdownDrain: false,
+ },
+ },
[MessageQueue.calendarQueue]: {
priority: 4,
workerOptions: {
diff --git a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts
index 125bca4d2b1..ef0d9bb8001 100644
--- a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts
+++ b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts
@@ -9,6 +9,7 @@ export enum MessageQueue {
cronQueue = 'cron-queue',
emailQueue = 'email-queue',
campaignQueue = 'campaign-queue',
+ campaignSendQueue = 'campaign-send-queue',
calendarQueue = 'calendar-queue',
connectedAccountSyncWebhookQueue = 'connected-account-sync-webhook-queue',
contactCreationQueue = 'contact-creation-queue',
diff --git a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
index b1d74e9282e..3022ce84f3f 100644
--- a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
+++ b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts
@@ -1675,6 +1675,24 @@ export class ConfigVariables {
@CastToPositiveNumber()
EMAIL_SEND_RATE_LIMITING_LIMIT = 100;
+ @ConfigVariablesMetadata({
+ group: ConfigVariablesGroup.RATE_LIMITING,
+ description:
+ 'Time-to-live for the per-workspace outbound email send rate limiting window, in milliseconds',
+ type: ConfigVariableType.NUMBER,
+ })
+ @CastToPositiveNumber()
+ EMAIL_SEND_WORKSPACE_RATE_LIMITING_TTL_IN_MS = 10_000;
+
+ @ConfigVariablesMetadata({
+ group: ConfigVariablesGroup.RATE_LIMITING,
+ description:
+ 'Maximum number of emails a single workspace may send in the rate limiting window. Applies on top of the server-wide limit, so set it below that one to stop a single workspace consuming the whole instance budget with one campaign. Left equal to the server-wide limit it never binds first',
+ type: ConfigVariableType.NUMBER,
+ })
+ @CastToPositiveNumber()
+ EMAIL_SEND_WORKSPACE_RATE_LIMITING_LIMIT = 100;
+
@ConfigVariablesMetadata({
group: ConfigVariablesGroup.RATE_LIMITING,
description:
diff --git a/packages/twenty-server/src/engine/core-modules/usage-limit/constants/usage-limit-definitions.constant.ts b/packages/twenty-server/src/engine/core-modules/usage-limit/constants/usage-limit-definitions.constant.ts
index 1efddf90107..01a3b15bee7 100644
--- a/packages/twenty-server/src/engine/core-modules/usage-limit/constants/usage-limit-definitions.constant.ts
+++ b/packages/twenty-server/src/engine/core-modules/usage-limit/constants/usage-limit-definitions.constant.ts
@@ -60,7 +60,20 @@ export const USAGE_LIMIT_DEFINITIONS: Record<
speed: {
allowedOperationTypes: [UsageOperationType.EMAIL_SEND],
allowedSpenderTypes: ['workspace'],
+ // Two buckets, and a send has to fit both. The workspace one keeps a
+ // single tenant's campaign from spending the whole instance budget; the
+ // server-wide one is what actually protects the provider account. The
+ // narrower scope is declared first so it names the scope when a refusal
+ // reports which limit was hit.
defaults: [
+ {
+ spenderType: 'workspace',
+ counterScope: 'perWorkspace',
+ limitValueConfigVariable: 'EMAIL_SEND_WORKSPACE_RATE_LIMITING_LIMIT',
+ windowMsConfigVariable:
+ 'EMAIL_SEND_WORKSPACE_RATE_LIMITING_TTL_IN_MS',
+ isOverridable: true,
+ },
{
spenderType: 'workspace',
counterScope: 'crossWorkspace',
diff --git a/packages/twenty-server/src/engine/core-modules/usage-limit/services/usage-limit-speed.service.ts b/packages/twenty-server/src/engine/core-modules/usage-limit/services/usage-limit-speed.service.ts
index 18541b2479b..023dde1e149 100644
--- a/packages/twenty-server/src/engine/core-modules/usage-limit/services/usage-limit-speed.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/usage-limit/services/usage-limit-speed.service.ts
@@ -73,6 +73,7 @@ export class UsageLimitSpeedService {
spenderId: outcome.exhausted.spenderId,
operationType,
limitValue: outcome.exhausted.refillPerWindow,
+ burstValue: outcome.exhausted.burst,
remaining: 0,
periodCount: Math.ceil(outcome.exhausted.windowMs / 1000),
periodUnit: 'second',
diff --git a/packages/twenty-server/src/engine/core-modules/usage-limit/types/exhausted-scope.type.ts b/packages/twenty-server/src/engine/core-modules/usage-limit/types/exhausted-scope.type.ts
index f0083d94534..7d235530a51 100644
--- a/packages/twenty-server/src/engine/core-modules/usage-limit/types/exhausted-scope.type.ts
+++ b/packages/twenty-server/src/engine/core-modules/usage-limit/types/exhausted-scope.type.ts
@@ -13,6 +13,11 @@ export type ExhaustedScope = {
spenderId: string | null;
operationType: UsageOperationType;
limitValue: number;
+ // Speed limits only. What admission is actually tested against: a bucket
+ // never holds more than its burst, so a cost above it can never be admitted
+ // however long the caller waits, while limitValue only says how fast it
+ // refills.
+ burstValue?: number;
remaining: number;
periodCount: number | null;
periodUnit: PeriodUnit | null;
diff --git a/packages/twenty-server/src/engine/core-modules/usage-limit/utils/__tests__/build-speed-buckets.util.spec.ts b/packages/twenty-server/src/engine/core-modules/usage-limit/utils/__tests__/build-speed-buckets.util.spec.ts
index 22f09bb7b73..2335c153aae 100644
--- a/packages/twenty-server/src/engine/core-modules/usage-limit/utils/__tests__/build-speed-buckets.util.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/usage-limit/utils/__tests__/build-speed-buckets.util.spec.ts
@@ -331,4 +331,38 @@ describe('buildSpeedBuckets with limits configured', () => {
}),
]);
});
+ it('builds a workspace bucket and a server-wide bucket for an email send, narrowest first', () => {
+ const systemContext = { type: 'system', workspace } as WorkspaceAuthContext;
+
+ const buckets = buildSpeedBuckets({
+ speedLimitDefaults: [
+ {
+ spenderType: 'workspace',
+ counterScope: 'perWorkspace',
+ maxTokens: 50,
+ windowMs: 10_000,
+ isOverridable: true,
+ },
+ {
+ spenderType: 'workspace',
+ counterScope: 'crossWorkspace',
+ maxTokens: 100,
+ windowMs: 10_000,
+ isOverridable: false,
+ },
+ ],
+ limits: [],
+ authContext: systemContext,
+ resourceType: UsageResourceType.EMAIL,
+ operationType: UsageOperationType.EMAIL_SEND,
+ });
+
+ // A send has to fit both, and the workspace bucket comes first so a refusal
+ // names it rather than the server-wide one.
+ expect(buckets.map((bucket) => bucket.key)).toEqual([
+ '{workspace-1}:speed:EMAIL:EMAIL_SEND:workspace:-:10',
+ '{server}:speed:EMAIL:EMAIL_SEND:workspace:-:10',
+ ]);
+ expect(buckets.map((bucket) => bucket.burst)).toEqual([50, 100]);
+ });
});
diff --git a/packages/twenty-server/src/modules/emailing/constants/skip-event-emission.constant.ts b/packages/twenty-server/src/modules/emailing/constants/skip-event-emission.constant.ts
new file mode 100644
index 00000000000..5acf251e347
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/constants/skip-event-emission.constant.ts
@@ -0,0 +1,4 @@
+// Campaign rows are machine-generated and nothing subscribes to them: no
+// webhook, workflow trigger or timeline activity. Emitting would cost a
+// snapshot SELECT of every row written plus a timeline row per recipient.
+export const SKIP_EVENT_EMISSION = { shouldSkipEventEmission: true };
diff --git a/packages/twenty-server/src/modules/emailing/emailing.module.ts b/packages/twenty-server/src/modules/emailing/emailing.module.ts
index 269f70c5c53..79c291478d3 100644
--- a/packages/twenty-server/src/modules/emailing/emailing.module.ts
+++ b/packages/twenty-server/src/modules/emailing/emailing.module.ts
@@ -38,6 +38,8 @@ import { MessageCampaignRecoveryService } from 'src/modules/emailing/services/me
import { MessageCampaignStatisticsService } from 'src/modules/emailing/services/message-campaign-statistics.service';
import { MessageCampaignAudienceService } from 'src/modules/emailing/services/message-campaign-audience.service';
import { MessageCampaignDeliveryFeedbackService } from 'src/modules/emailing/services/message-campaign-delivery-feedback.service';
+import { MessageCampaignBatchDeliveryService } from 'src/modules/emailing/services/message-campaign-batch-delivery.service';
+import { CampaignSendSlotService } from 'src/modules/emailing/services/campaign-send-slot.service';
import { MessageCampaignDeliveryService } from 'src/modules/emailing/services/message-campaign-delivery.service';
import { MessageCampaignLifecycleService } from 'src/modules/emailing/services/message-campaign-lifecycle.service';
import { MessageCampaignMaterializationService } from 'src/modules/emailing/services/message-campaign-materialization.service';
@@ -77,7 +79,9 @@ import { SaveCampaignTool } from 'src/modules/emailing/tools/save-campaign-tool'
EmailBillingService,
MessageCampaignService,
MessageCampaignAudienceService,
+ CampaignSendSlotService,
MessageCampaignDeliveryService,
+ MessageCampaignBatchDeliveryService,
MessageCampaignDeliveryFeedbackService,
MessageCampaignLifecycleService,
MessageCampaignMaterializationService,
@@ -106,7 +110,9 @@ import { SaveCampaignTool } from 'src/modules/emailing/tools/save-campaign-tool'
EmailingDomainSenderService,
EmailBillingService,
MessageCampaignService,
+ CampaignSendSlotService,
MessageCampaignDeliveryService,
+ MessageCampaignBatchDeliveryService,
MessageCampaignDeliveryFeedbackService,
MessageCampaignMaterializationService,
MessageCampaignDraftService,
diff --git a/packages/twenty-server/src/modules/emailing/jobs/send-campaign-email-batch.job.ts b/packages/twenty-server/src/modules/emailing/jobs/send-campaign-email-batch.job.ts
new file mode 100644
index 00000000000..72436048f13
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/jobs/send-campaign-email-batch.job.ts
@@ -0,0 +1,18 @@
+import { SEND_CAMPAIGN_EMAIL_BATCH_JOB } from 'src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant';
+import { type SendCampaignEmailBatchJobData } from 'src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type';
+import { Process } from 'src/engine/core-modules/message-queue/decorators/process.decorator';
+import { Processor } from 'src/engine/core-modules/message-queue/decorators/processor.decorator';
+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
+import { MessageCampaignBatchDeliveryService } from 'src/modules/emailing/services/message-campaign-batch-delivery.service';
+
+@Processor(MessageQueue.campaignSendQueue)
+export class SendCampaignEmailBatchJob {
+ constructor(
+ private readonly messageCampaignBatchDeliveryService: MessageCampaignBatchDeliveryService,
+ ) {}
+
+ @Process(SEND_CAMPAIGN_EMAIL_BATCH_JOB)
+ async handle(data: SendCampaignEmailBatchJobData): Promise<void> {
+ await this.messageCampaignBatchDeliveryService.processSendBatchJob(data);
+ }
+}
diff --git a/packages/twenty-server/src/modules/emailing/services/__tests__/message-campaign-batch-delivery.service.spec.ts b/packages/twenty-server/src/modules/emailing/services/__tests__/message-campaign-batch-delivery.service.spec.ts
new file mode 100644
index 00000000000..824412df6c3
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/services/__tests__/message-campaign-batch-delivery.service.spec.ts
@@ -0,0 +1,473 @@
+import { getDataSourceToken } from '@nestjs/typeorm';
+import { Test, type TestingModule } from '@nestjs/testing';
+import { EMAIL_DOCUMENT_SCHEMA_VERSION } from 'twenty-shared/utils';
+
+import {
+ EmailingDomainDriverException,
+ EmailingDomainDriverExceptionCode,
+} from 'src/engine/core-modules/emailing-domain/drivers/exceptions/emailing-domain-driver.exception';
+import { CAMPAIGN_DELIVERY_STATE } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-state.constant';
+import { type SendSlotRefusal } from 'src/engine/core-modules/emailing-domain/types/send-slot-refusal.type';
+import { CAMPAIGN_FAILURE_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant';
+import { CLAIMABLE_CAMPAIGN_DELIVERY_STATES } from 'src/engine/core-modules/emailing-domain/constants/claimable-campaign-delivery-states.constant';
+import { CampaignDeliveryEntity } from 'src/engine/core-modules/emailing-domain/campaign-delivery.entity';
+import { getQueueToken } from 'src/engine/core-modules/message-queue/utils/get-queue-token.util';
+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
+import { getWorkspaceScopedRepositoryToken } from 'src/engine/twenty-orm/workspace-scoped-repository/get-workspace-scoped-repository-token.util';
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
+import { CampaignSendSlotService } from 'src/modules/emailing/services/campaign-send-slot.service';
+import { EmailBillingService } from 'src/modules/emailing/services/email-billing.service';
+import { EmailingDomainSenderService } from 'src/modules/emailing/services/emailing-domain-sender.service';
+import { CampaignVariableService } from 'src/modules/emailing/services/campaign-variable.service';
+import { MessageCampaignBatchDeliveryService } from 'src/modules/emailing/services/message-campaign-batch-delivery.service';
+import { MessageCampaignLifecycleService } from 'src/modules/emailing/services/message-campaign-lifecycle.service';
+import { MessageCampaignStatisticsService } from 'src/modules/emailing/services/message-campaign-statistics.service';
+import { MessageChannelMessageAssociationWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message-channel-message-association.workspace-entity';
+import { MessageWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message.workspace-entity';
+
+const WORKSPACE_ID = 'ec9b0b2a-4c02-4d1e-9f2a-9b1c0a5d7e31';
+const CAMPAIGN_ID = 'b1f0c6d5-3f9b-4a4e-9a5c-2f7d8e6b4a10';
+
+const BODY_TEMPLATE = JSON.stringify({
+ type: 'doc',
+ attrs: { schemaVersion: EMAIL_DOCUMENT_SCHEMA_VERSION },
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hi' }] }],
+});
+
+const buildRecipient = (index: number) => ({
+ messageId: `message-${index}`,
+ personId: `person-${index}`,
+ email: `person${index}@example.com`,
+});
+
+const buildJobData = (recipientCount: number) => ({
+ workspaceId: WORKSPACE_ID,
+ campaignId: CAMPAIGN_ID,
+ emailingDomainId: 'domain-1',
+ userWorkspaceId: 'user-workspace-1',
+ recipients: Array.from({ length: recipientCount }, (_unused, index) =>
+ buildRecipient(index),
+ ),
+});
+
+// buildCampaignDeliverySettleQuery passes the settlement columns as parallel
+// arrays; this reads one back as rows.
+const decodeSettleCall = (parameters: unknown[]) => {
+ const [ids, states, , failureReasons, providerMessageIds] =
+ parameters as string[][];
+
+ return ids.map((id, index) => ({
+ deliveryId: id,
+ state: states[index],
+ failureReason: failureReasons[index],
+ providerMessageId: providerMessageIds[index],
+ }));
+};
+
+const buildHarness = () => {
+ const claimedIds: string[] = [];
+
+ const queryBuilder = {
+ update: () => queryBuilder,
+ set: () => queryBuilder,
+ where: () => queryBuilder,
+ andWhere: () => queryBuilder,
+ returning: () => queryBuilder,
+ execute: jest.fn(async () => ({
+ raw: claimedIds.map((id) => ({ id })),
+ })),
+ };
+
+ const campaignDeliveryRepository = {
+ createQueryBuilder: () => queryBuilder,
+ update: jest.fn(
+ async (
+ _workspaceId: string,
+ _criteria: unknown,
+ _update: Record<string, unknown>,
+ ) => ({ affected: claimedIds.length }),
+ ),
+ };
+
+ const messageRepository = { update: jest.fn(async () => ({ affected: 1 })) };
+ const associationRepository = {
+ update: jest.fn(async () => ({ affected: 1 })),
+ };
+ const personRepository = {
+ find: jest.fn(async () => [{ id: 'person-0' }, { id: 'person-1' }]),
+ };
+
+ const workspaceOrmManager = {
+ executeInWorkspaceContext: jest.fn(
+ async (callback: () => Promise<unknown>) => callback(),
+ ),
+ getRepository: jest.fn((entity: unknown) => {
+ if (entity === MessageWorkspaceEntity) {
+ return messageRepository;
+ }
+
+ if (entity === MessageChannelMessageAssociationWorkspaceEntity) {
+ return associationRepository;
+ }
+
+ return personRepository;
+ }),
+ };
+
+ const emailingDomainSenderService = {
+ sendEmailBatch: jest.fn(),
+ findBlockedRecipientAddresses: jest.fn(async () => new Set<string>()),
+ };
+ const emailBillingService = {
+ getEmailCreditContext: jest.fn(async () => ({ hasCredits: true })),
+ billSentEmails: jest.fn(async () => undefined),
+ };
+ const campaignVariableService = {
+ buildVariablesForPerson: jest.fn(async () => ({})),
+ };
+ const messageCampaignLifecycleService = {
+ findRunningCampaign: jest.fn(async () => ({
+ id: CAMPAIGN_ID,
+ subject: 'Newsletter',
+ bodyTemplate: BODY_TEMPLATE,
+ fromAddress: { primaryEmail: '[email protected]' },
+ unsubscribeTopicId: null,
+ })),
+ finalizeCampaignIfComplete: jest.fn(async () => undefined),
+ };
+ const messageCampaignStatisticsService = {
+ scheduleRefresh: jest.fn(async () => undefined),
+ };
+ const campaignSendSlotService = {
+ findSendSlotRefusal: jest.fn(
+ async (): Promise<SendSlotRefusal | null> => null,
+ ),
+ };
+ const messageQueueService = {
+ bulkAdd: jest.fn(
+ async (
+ _jobName: string,
+ _jobs: { data: { recipients: unknown[] } }[],
+ _options?: unknown,
+ ) => [],
+ ),
+ };
+ const dataSource = {
+ query: jest.fn(async (_sql: string, _parameters: unknown[]) =>
+ claimedIds.map((id) => ({ id })),
+ ),
+ };
+
+ const buildService = async () => {
+ const module: TestingModule = await Test.createTestingModule({
+ providers: [
+ MessageCampaignBatchDeliveryService,
+ {
+ provide: getWorkspaceScopedRepositoryToken(CampaignDeliveryEntity),
+ useValue: campaignDeliveryRepository,
+ },
+ { provide: getDataSourceToken(), useValue: dataSource },
+ {
+ provide: getQueueToken(MessageQueue.campaignSendQueue),
+ useValue: messageQueueService,
+ },
+ { provide: WorkspaceOrmManager, useValue: workspaceOrmManager },
+ {
+ provide: EmailingDomainSenderService,
+ useValue: emailingDomainSenderService,
+ },
+ { provide: EmailBillingService, useValue: emailBillingService },
+ { provide: CampaignVariableService, useValue: campaignVariableService },
+ {
+ provide: MessageCampaignLifecycleService,
+ useValue: messageCampaignLifecycleService,
+ },
+ {
+ provide: MessageCampaignStatisticsService,
+ useValue: messageCampaignStatisticsService,
+ },
+ { provide: CampaignSendSlotService, useValue: campaignSendSlotService },
+ ],
+ }).compile();
+
+ return module.get(MessageCampaignBatchDeliveryService);
+ };
+
+ return {
+ buildService,
+ claimedIds,
+ campaignDeliveryRepository,
+ dataSource,
+ emailingDomainSenderService,
+ messageCampaignLifecycleService,
+ campaignSendSlotService,
+ messageQueueService,
+ messageRepository,
+ associationRepository,
+ emailBillingService,
+ };
+};
+
+describe('MessageCampaignBatchDeliveryService', () => {
+ // Compiling the email document awaits a renderer that never settles under
+ // the suite's fake timers.
+ beforeAll(() => {
+ jest.useRealTimers();
+ });
+
+ it('does not rethrow a provider failure no retry can fix, so the campaign still finalizes', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1');
+ harness.emailingDomainSenderService.sendEmailBatch.mockRejectedValue(
+ new EmailingDomainDriverException(
+ 'Sending is not configured',
+ EmailingDomainDriverExceptionCode.CONFIGURATION_ERROR,
+ ),
+ );
+
+ await expect(
+ (await harness.buildService()).processSendBatchJob(buildJobData(2)),
+ ).resolves.toBeUndefined();
+
+ expect(
+ harness.messageCampaignLifecycleService.finalizeCampaignIfComplete,
+ ).toHaveBeenCalled();
+ });
+
+ it('settles a terminal provider failure into its own state rather than back to queued', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0');
+ harness.emailingDomainSenderService.sendEmailBatch.mockRejectedValue(
+ new EmailingDomainDriverException(
+ 'Sandbox account',
+ EmailingDomainDriverExceptionCode.SANDBOX_ACCOUNT,
+ ),
+ );
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(1));
+
+ const settleCall =
+ harness.campaignDeliveryRepository.update.mock.calls.find(
+ ([, , update]) =>
+ (update as { failureReason?: string }).failureReason ===
+ CAMPAIGN_FAILURE_REASON.SANDBOX_ACCOUNT,
+ );
+
+ expect(settleCall).toBeDefined();
+ expect((settleCall?.[2] as { state: string }).state).toBe(
+ CAMPAIGN_DELIVERY_STATE.FAILED,
+ );
+ });
+
+ it('rethrows a retriable provider failure so the job runs again', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0');
+ harness.emailingDomainSenderService.sendEmailBatch.mockRejectedValue(
+ new EmailingDomainDriverException(
+ 'Upstream hiccup',
+ EmailingDomainDriverExceptionCode.TEMPORARY_ERROR,
+ ),
+ );
+
+ await expect(
+ (await harness.buildService()).processSendBatchJob(buildJobData(1)),
+ ).rejects.toThrow('Upstream hiccup');
+ });
+
+ it('keeps mail the provider accepted out of any state a retry could claim', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0');
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [
+ { recipientIndex: 0, messageId: 'provider-0', errorMessage: null },
+ ],
+ suppressedRecipientIndexes: [],
+ });
+ // The settle statement fails once; the rescue reruns it.
+ harness.dataSource.query
+ .mockRejectedValueOnce(new Error('settle exploded'))
+ .mockResolvedValue([{ id: 'message-0' }]);
+
+ await expect(
+ (await harness.buildService()).processSendBatchJob(buildJobData(1)),
+ ).rejects.toThrow('settle exploded');
+
+ const [rescued] = decodeSettleCall(
+ harness.dataSource.query.mock.calls[1][1],
+ );
+
+ expect(CLAIMABLE_CAMPAIGN_DELIVERY_STATES).not.toContain(rescued.state);
+ // Keeping the provider id is what lets a later bounce or delivery webhook
+ // still find this row.
+ expect(rescued.providerMessageId).toBe('provider-0');
+ expect(rescued.failureReason).toBe(CAMPAIGN_FAILURE_REASON.SETTLEMENT_LOST);
+ });
+
+ it('does not count a recipient the provider rejected as sent when settling throws', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1');
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [
+ { recipientIndex: 0, messageId: 'provider-0', errorMessage: null },
+ { recipientIndex: 1, messageId: null, errorMessage: 'rejected' },
+ ],
+ suppressedRecipientIndexes: [],
+ });
+ harness.dataSource.query
+ .mockRejectedValueOnce(new Error('settle exploded'))
+ .mockResolvedValue([]);
+
+ await expect(
+ (await harness.buildService()).processSendBatchJob(buildJobData(2)),
+ ).rejects.toThrow('settle exploded');
+
+ const rescuedRows = harness.dataSource.query.mock.calls
+ .slice(1)
+ .flatMap(([, parameters]) => decodeSettleCall(parameters));
+
+ expect(
+ rescuedRows.find((row) => row.deliveryId === 'message-0')?.state,
+ ).toBe(CAMPAIGN_DELIVERY_STATE.SENT);
+ expect(
+ rescuedRows.find((row) => row.deliveryId === 'message-1')?.state,
+ ).toBe(CAMPAIGN_DELIVERY_STATE.FAILED);
+ });
+
+ it('settles the accepted rows before the rejected ones, so a half-failed rescue cannot re-send', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1');
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [
+ { recipientIndex: 0, messageId: 'provider-0', errorMessage: null },
+ { recipientIndex: 1, messageId: null, errorMessage: 'rejected' },
+ ],
+ suppressedRecipientIndexes: [],
+ });
+ harness.dataSource.query
+ .mockRejectedValueOnce(new Error('settle exploded'))
+ .mockResolvedValue([]);
+
+ await expect(
+ (await harness.buildService()).processSendBatchJob(buildJobData(2)),
+ ).rejects.toThrow('settle exploded');
+
+ // Whatever the rescue does not reach is re-queued by the finally block, so
+ // the rows the provider took have to be settled by the first of the two.
+ const [acceptedFirst] = decodeSettleCall(
+ harness.dataSource.query.mock.calls[1][1],
+ );
+
+ expect(acceptedFirst.deliveryId).toBe('message-0');
+ });
+
+ it('records the message, the association and the billing for a delivered batch', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0');
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [
+ { recipientIndex: 0, messageId: 'provider-0', errorMessage: null },
+ ],
+ suppressedRecipientIndexes: [],
+ });
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(1));
+
+ expect(harness.messageRepository.update).toHaveBeenCalledWith(
+ 'message-0',
+ expect.objectContaining({ headerMessageId: 'provider-0' }),
+ );
+ expect(harness.associationRepository.update).toHaveBeenCalledWith(
+ { messageId: 'message-0' },
+ expect.objectContaining({ messageExternalId: 'provider-0' }),
+ );
+ expect(harness.emailBillingService.billSentEmails).toHaveBeenCalledWith(
+ expect.objectContaining({ sentEmailCount: 1 }),
+ );
+ });
+
+ it('asks for slots for the deliverable recipients only, not the suppressed ones', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1', 'message-2');
+ harness.emailingDomainSenderService.findBlockedRecipientAddresses.mockResolvedValue(
+ );
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [
+ { recipientIndex: 0, messageId: 'provider-0', errorMessage: null },
+ ],
+ suppressedRecipientIndexes: [1, 2],
+ });
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(3));
+
+ expect(
+ harness.campaignSendSlotService.findSendSlotRefusal,
+ ).toHaveBeenCalledWith(expect.objectContaining({ requestedSlotCount: 1 }));
+ });
+
+ it('spends no send capacity at all when every recipient is suppressed', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0');
+ harness.emailingDomainSenderService.findBlockedRecipientAddresses.mockResolvedValue(
+ new Set(['[email protected]']),
+ );
+ harness.emailingDomainSenderService.sendEmailBatch.mockResolvedValue({
+ entries: [],
+ suppressedRecipientIndexes: [0],
+ });
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(1));
+
+ expect(
+ harness.campaignSendSlotService.findSendSlotRefusal,
+ ).not.toHaveBeenCalled();
+ });
+
+ it('splits a rate-limited batch the workspace limit could never admit whole', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1', 'message-2');
+ harness.campaignSendSlotService.findSendSlotRefusal.mockResolvedValue({
+ retryDelayMs: 1000,
+ windowMs: 1000,
+ limitValue: 1,
+ });
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(3));
+
+ expect(harness.messageQueueService.bulkAdd).toHaveBeenCalledTimes(1);
+
+ const requeuedRecipientCounts =
+ harness.messageQueueService.bulkAdd.mock.calls[0][1].map(
+ (job) => job.data.recipients.length,
+ );
+
+ expect(requeuedRecipientCounts).toEqual([1, 1, 1]);
+ });
+
+ it('re-queues a rate-limited batch whole when it already fits the limit', async () => {
+ const harness = buildHarness();
+
+ harness.claimedIds.push('message-0', 'message-1');
+ harness.campaignSendSlotService.findSendSlotRefusal.mockResolvedValue({
+ retryDelayMs: 1000,
+ windowMs: 1000,
+ limitValue: 50,
+ });
+
+ await (await harness.buildService()).processSendBatchJob(buildJobData(2));
+
+ expect(harness.messageQueueService.bulkAdd.mock.calls[0][1]).toHaveLength(
+ 1,
+ );
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-send-slot.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-send-slot.service.ts
new file mode 100644
index 00000000000..36f2b0b4503
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/services/campaign-send-slot.service.ts
@@ -0,0 +1,59 @@
+import { Injectable } from '@nestjs/common';
+
+import { SEND_SLOT_RETRY } from 'src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant';
+import { type SendSlotRefusal } from 'src/engine/core-modules/emailing-domain/types/send-slot-refusal.type';
+import {
+ UsageLimitException,
+ UsageLimitExceptionCode,
+} from 'src/engine/core-modules/usage-limit/exceptions/usage-limit.exception';
+import { UsageLimitSpeedService } from 'src/engine/core-modules/usage-limit/services/usage-limit-speed.service';
+import { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-operation-type.enum';
+import { UsageResourceType } from 'src/engine/core-modules/usage/enums/usage-resource-type.enum';
+import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
+
+@Injectable()
+export class CampaignSendSlotService {
+ constructor(
+ private readonly usageLimitSpeedService: UsageLimitSpeedService,
+ ) {}
+
+ // Returns null when the slots were consumed, or how long to wait when the
+ // workspace token bucket refused them.
+ async findSendSlotRefusal({
+ workspaceId,
+ requestedSlotCount = 1,
+ }: {
+ workspaceId: string;
+ requestedSlotCount?: number;
+ }): Promise<SendSlotRefusal | null> {
+ try {
+ await this.usageLimitSpeedService.consumeOrThrow({
+ resourceType: UsageResourceType.EMAIL,
+ operationType: UsageOperationType.EMAIL_SEND,
+ authContext: buildSystemAuthContext(workspaceId),
+ cost: requestedSlotCount,
+ });
+
+ return null;
+ } catch (error) {
+ if (
+ !(error instanceof UsageLimitException) ||
+ error.code !== UsageLimitExceptionCode.RATE_LIMITED
+ ) {
+ throw error;
+ }
+
+ return {
+ retryDelayMs: Math.max(
+ error.exhaustedScope?.retryAfterMs ?? 0,
+ SEND_SLOT_RETRY.minDelayMs,
+ ),
+ windowMs:
+ error.exhaustedScope?.periodUnit === 'second'
+ ? (error.exhaustedScope.periodCount ?? 0) * 1000
+ : 0,
+ limitValue: error.exhaustedScope?.limitValue ?? null,
+ };
+ }
+ }
+}
diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-variable.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-variable.service.ts
index d1975fecbd9..0e30fc552ab 100644
--- a/packages/twenty-server/src/modules/emailing/services/campaign-variable.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/campaign-variable.service.ts
@@ -14,6 +14,8 @@ import {
} from 'src/engine/core-modules/emailing-domain/exceptions/emailing-domain.exception';
import { getFlatFieldsFromFlatObjectMetadata } from 'src/engine/api/graphql/workspace-schema-builder/utils/get-flat-fields-for-flat-object-metadata.util';
import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { type FlatFieldMetadataMaps } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata-maps.type';
+import { type FlatObjectMetadataMaps } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata-maps.type';
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
import { type PersonWorkspaceEntity } from 'src/modules/person/standard-objects/person.workspace-entity';
@@ -22,12 +24,28 @@ export type PersonCampaignVariables = {
knownVariableNames: Set<string>;
};
+type PersonVariableSchema = PersonCampaignVariables & {
+ fieldsByName: Map<string, FlatFieldMetadata>;
+};
+
const COMPUTED_VARIABLE_NAMES = ['fullName', 'personId'];
const MAX_VARIABLES_IN_ERROR_MESSAGE = 40;
+const PERSON_FIELD_CACHE_KEYS = [
+ 'flatObjectMetadataMaps',
+ 'flatFieldMetadataMaps',
+] as const;
+
+const MAX_CACHED_WORKSPACE_SCHEMAS = 100;
+
@Injectable()
export class CampaignVariableService {
+ private readonly schemaByWorkspaceId = new Map<
+ string,
+ { hash: string; schema: PersonVariableSchema }
+ >();
+
constructor(
private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
) {}
@@ -35,14 +53,59 @@ export class CampaignVariableService {
async getPersonCampaignVariables(
workspaceId: string,
): Promise<PersonCampaignVariables> {
- const fields = await this.getPersonFields(workspaceId);
+ return this.getPersonVariableSchema(workspaceId);
+ }
+
+ private async getPersonVariableSchema(
+ workspaceId: string,
+ ): Promise<PersonVariableSchema> {
+ const { data, hashes } =
+ await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMapsWithHashes(
+ { workspaceId, flatMapsKeys: [...PERSON_FIELD_CACHE_KEYS] },
+ );
+
+ const hash = PERSON_FIELD_CACHE_KEYS.map(
+ (cacheKey) => hashes[cacheKey] ?? '',
+ ).join(':');
+
+ const cached = this.schemaByWorkspaceId.get(workspaceId);
+
+ if (cached?.hash === hash) {
+ this.schemaByWorkspaceId.delete(workspaceId);
+ this.schemaByWorkspaceId.set(workspaceId, cached);
+
+ return cached.schema;
+ }
+
+ const fields = this.extractPersonFields(data);
const definitions = listCampaignVariablesForFields(fields);
- const knownVariableNames = new Set<string>([
- ...definitions.map((definition) => definition.name),
- ...COMPUTED_VARIABLE_NAMES,
- ]);
+ const schema: PersonVariableSchema = {
+ definitions,
+ knownVariableNames: new Set<string>([
+ ...definitions.map((definition) => definition.name),
+ ...COMPUTED_VARIABLE_NAMES,
+ ]),
+ fieldsByName: new Map(fields.map((field) => [field.name, field])),
+ };
+
+ this.schemaByWorkspaceId.set(workspaceId, { hash, schema });
+ this.evictLeastRecentlyUsedSchemas();
+
+ return schema;
+ }
+
+ private evictLeastRecentlyUsedSchemas(): void {
+ while (this.schemaByWorkspaceId.size > MAX_CACHED_WORKSPACE_SCHEMAS) {
+ const leastRecentlyUsedWorkspaceId = this.schemaByWorkspaceId
+ .keys()
+ .next().value;
- return { definitions, knownVariableNames };
+ if (!isDefined(leastRecentlyUsedWorkspaceId)) {
+ return;
+ }
+
+ this.schemaByWorkspaceId.delete(leastRecentlyUsedWorkspaceId);
+ }
}
async assertKnownVariables(
@@ -78,8 +141,8 @@ export class CampaignVariableService {
workspaceId: string,
person: PersonWorkspaceEntity | null,
): Promise<Record<string, string>> {
- const { definitions } = await this.getPersonCampaignVariables(workspaceId);
- const fieldsByName = await this.getPersonFieldsByName(workspaceId);
+ const { definitions, fieldsByName } =
+ await this.getPersonVariableSchema(workspaceId);
const variables: Record<string, string> = {};
@@ -102,17 +165,13 @@ export class CampaignVariableService {
return variables;
}
- private async getPersonFields(
- workspaceId: string,
- ): Promise<FlatFieldMetadata[]> {
- const { flatObjectMetadataMaps, flatFieldMetadataMaps } =
- await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
- {
- workspaceId,
- flatMapsKeys: ['flatObjectMetadataMaps', 'flatFieldMetadataMaps'],
- },
- );
-
+ private extractPersonFields({
+ flatObjectMetadataMaps,
+ flatFieldMetadataMaps,
+ }: {
+ flatObjectMetadataMaps: FlatObjectMetadataMaps;
+ flatFieldMetadataMaps: FlatFieldMetadataMaps;
+ }): FlatFieldMetadata[] {
const personFlatObject =
flatObjectMetadataMaps.byUniversalIdentifier[
STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person
@@ -128,14 +187,6 @@ export class CampaignVariableService {
);
}
- private async getPersonFieldsByName(
- workspaceId: string,
- ): Promise<Map<string, FlatFieldMetadata>> {
- const fields = await this.getPersonFields(workspaceId);
-
- return new Map(fields.map((field) => [field.name, field]));
- }
-
private resolveValue(
person: PersonWorkspaceEntity | null,
path: string,
diff --git a/packages/twenty-server/src/modules/emailing/services/emailing-domain-sender.service.ts b/packages/twenty-server/src/modules/emailing/services/emailing-domain-sender.service.ts
index c5d136bfe7a..77481692c8d 100644
--- a/packages/twenty-server/src/modules/emailing/services/emailing-domain-sender.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/emailing-domain-sender.service.ts
@@ -13,12 +13,16 @@ import { EmailingDomainDriverFactory } from 'src/engine/core-modules/emailing-do
import { EmailingDomainStatus } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-status.type';
import { EmailingDomainTenantStatus } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-tenant-status.type';
import { type EmailingDomainEmailContent } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-content.type';
+import { type EmailingDomainBatchRecipient } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-batch-recipient.type';
+import { type EmailingDomainEmailTemplate } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type';
+import { type EmailingDomainSendKind } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-kind.type';
import { type EmailingDomainSendEmailRequest } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-input.type';
import { type EmailingDomainSendEmailResult } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-send-email-result.type';
import { EmailingDomainEntity } from 'src/engine/core-modules/emailing-domain/emailing-domain.entity';
import { formatMessageFromHeader } from 'src/modules/messaging/message-outbound-manager/utils/format-message-from-header.util';
import { MessageSuppressionService } from 'src/modules/emailing/services/message-suppression.service';
import { MessageChannelEntity } from 'src/engine/metadata-modules/message-channel/entities/message-channel.entity';
+import { type CampaignBatchSendOutcome } from 'src/modules/emailing/types/campaign-batch-send-outcome.type';
import { type DeliverableRecipients } from 'src/engine/core-modules/emailing-domain/types/deliverable-recipients.type';
import { isSuppressionBlockingSend } from 'src/engine/core-modules/emailing-domain/utils/is-suppression-blocking-send.util';
import { getDomainFromEmail } from 'src/utils/get-domain-from-email';
@@ -82,6 +86,128 @@ export class EmailingDomainSenderService {
.sendEmail(emailToSend);
}
+ async sendEmailBatch({
+ workspaceId,
+ emailingDomainId,
+ sendKind,
+ from,
+ template,
+ recipients,
+ unsubscribeTopicId,
+ }: {
+ workspaceId: string;
+ emailingDomainId: string;
+ sendKind: EmailingDomainSendKind;
+ from: string;
+ template: EmailingDomainEmailTemplate;
+ recipients: EmailingDomainBatchRecipient[];
+ unsubscribeTopicId?: string;
+ }): Promise<CampaignBatchSendOutcome> {
+ const emailingDomain = await this.findEmailingDomainByIdOrThrow(
+ workspaceId,
+ emailingDomainId,
+ );
+
+ this.assertDomainCanSend(emailingDomain, from);
+
+ // Resolved here, immediately before the handoff, and never taken from the
+ // caller: everything between choosing recipients and sending them is time
+ // in which one of them can unsubscribe.
+ const blockedAddresses = await this.findBlockedRecipientAddresses({
+ workspaceId,
+ sendKind,
+ emailAddresses: recipients.map((recipient) => recipient.email),
+ unsubscribeTopicId,
+ });
+
+ const deliverableRecipients: EmailingDomainBatchRecipient[] = [];
+ const deliverableRecipientIndexes: number[] = [];
+ const suppressedRecipientIndexes: number[] = [];
+
+ recipients.forEach((recipient, recipientIndex) => {
+ if (blockedAddresses.has(recipient.email.trim().toLowerCase())) {
+ suppressedRecipientIndexes.push(recipientIndex);
+
+ return;
+ }
+
+ deliverableRecipients.push(recipient);
+ deliverableRecipientIndexes.push(recipientIndex);
+ });
+
+ if (deliverableRecipients.length === 0) {
+ return { entries: [], suppressedRecipientIndexes };
+ }
+
+ const emailGroupChannel = await this.findEmailGroupChannel(
+ workspaceId,
+ from,
+ );
+
+ const { entries } = await this.emailingDomainDriverFactory
+ .getCurrentDriver()
+ .sendEmailBatch({
+ sendKind,
+ workspaceId,
+ domain: emailingDomain.domain,
+ emailingDomain,
+ from: formatMessageFromHeader({
+ fromEmail: from,
+ fromName: emailGroupChannel?.displayName,
+ }),
+ replyTo: isNonEmptyString(emailGroupChannel?.handle)
+ ? [emailGroupChannel.handle]
+ : undefined,
+ template,
+ recipients: deliverableRecipients,
+ unsubscribeTopicId,
+ });
+
+ return {
+ entries: entries.map((entry) => ({
+ recipientIndex: deliverableRecipientIndexes[entry.recipientIndex],
+ messageId: entry.messageId,
+ errorMessage: entry.errorMessage,
+ })),
+ suppressedRecipientIndexes,
+ };
+ }
+
+ // Exposed so a caller can tell who is deliverable before spending anything on
+ // their behalf. It is an estimate for that purpose only: sendEmailBatch
+ // resolves suppression again at the handoff, and that later answer is the one
+ // that decides who is mailed.
+ async findBlockedRecipientAddresses({
+ workspaceId,
+ sendKind,
+ emailAddresses,
+ unsubscribeTopicId,
+ }: {
+ workspaceId: string;
+ sendKind: EmailingDomainSendKind;
+ emailAddresses: string[];
+ unsubscribeTopicId?: string;
+ }): Promise<Set<string>> {
+ const suppressions =
+ await this.messageSuppressionService.findApplicableSuppressions({
+ workspaceId,
+ emailAddresses,
+ unsubscribeTopicId,
+ });
+
+ return new Set(
+ suppressions
+ .filter((suppression) =>
+ isSuppressionBlockingSend({
+ sendKind,
+ suppression,
+ unsubscribeTopicId,
+ }),
+ )
+ .map((suppression) => suppression.emailAddress),
+ );
+ }
+
private async findEmailGroupChannel(
workspaceId: string,
fromAddress: string,
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts
new file mode 100644
index 00000000000..6e6546e57eb
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-batch-delivery.service.ts
@@ -0,0 +1,682 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectDataSource } from '@nestjs/typeorm';
+
+import { DataSource, In } from 'typeorm';
+import { isDefined } from 'twenty-shared/utils';
+import { v4 } from 'uuid';
+
+import { CampaignDeliveryEntity } from 'src/engine/core-modules/emailing-domain/campaign-delivery.entity';
+import { SEND_CAMPAIGN_EMAIL_BATCH_JOB } from 'src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant';
+import { CAMPAIGN_DELIVERY_CLAIM_TTL_MS } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-claim-ttl-ms.constant';
+import { CAMPAIGN_DELIVERY_STATE } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-state.constant';
+import { CAMPAIGN_FAILURE_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant';
+import { CAMPAIGN_SEND_RETRY_BACKOFF } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-retry-backoff.constant';
+import { CAMPAIGN_SEND_RETRY_LIMIT } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-retry-limit.constant';
+import { CAMPAIGN_SKIP_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-skip-reason.constant';
+import { CLAIMABLE_CAMPAIGN_DELIVERY_STATES } from 'src/engine/core-modules/emailing-domain/constants/claimable-campaign-delivery-states.constant';
+import { SEND_SLOT_RETRY } from 'src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant';
+import { type SendCampaignEmailBatchJobData } from 'src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type';
+import { type SendSlotRefusal } from 'src/engine/core-modules/emailing-domain/types/send-slot-refusal.type';
+import { applyReplacementTags } from 'src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util';
+import { InjectMessageQueue } from 'src/engine/core-modules/message-queue/decorators/message-queue.decorator';
+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
+import { MessageQueueService } from 'src/engine/core-modules/message-queue/services/message-queue.service';
+import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
+import { InjectWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/inject-workspace-scoped-repository.decorator';
+import { WorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/workspace-scoped-repository';
+import { SKIP_EVENT_EMISSION } from 'src/modules/emailing/constants/skip-event-emission.constant';
+import { CampaignSendSlotService } from 'src/modules/emailing/services/campaign-send-slot.service';
+import { CampaignVariableService } from 'src/modules/emailing/services/campaign-variable.service';
+import { EmailBillingService } from 'src/modules/emailing/services/email-billing.service';
+import { EmailingDomainSenderService } from 'src/modules/emailing/services/emailing-domain-sender.service';
+import { MessageCampaignLifecycleService } from 'src/modules/emailing/services/message-campaign-lifecycle.service';
+import { MessageCampaignStatisticsService } from 'src/modules/emailing/services/message-campaign-statistics.service';
+import { MessageCampaignWorkspaceEntity } from 'src/modules/emailing/standard-objects/message-campaign.workspace-entity';
+import { type EmailingDomainEmailTemplate } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type';
+import { type CampaignDeliverySettlement } from 'src/modules/emailing/types/campaign-delivery-settlement.type';
+import { type EmailCreditContext } from 'src/modules/emailing/types/email-credit-context.type';
+import { buildCampaignBatchReplacements } from 'src/modules/emailing/utils/build-campaign-batch-replacements.util';
+import { buildCampaignDeliverySettleQuery } from 'src/modules/emailing/utils/build-campaign-delivery-settle-query.util';
+import { compileCampaignBatchTemplate } from 'src/modules/emailing/utils/compile-campaign-batch-template.util';
+import { chunkRecipientsToAdmissibleSize } from 'src/modules/emailing/utils/chunk-recipients-to-admissible-size.util';
+import { computeSendSlotBackoffMs } from 'src/modules/emailing/utils/compute-send-slot-backoff-ms.util';
+import { resolveCampaignBatchSettlements } from 'src/modules/emailing/utils/resolve-campaign-batch-settlements.util';
+import { resolveCampaignSendFailure } from 'src/modules/emailing/utils/resolve-campaign-send-failure.util';
+import { MessageChannelMessageAssociationWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message-channel-message-association.workspace-entity';
+import { MessageWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message.workspace-entity';
+import { PersonWorkspaceEntity } from 'src/modules/person/standard-objects/person.workspace-entity';
+
+type BatchRecipient = SendCampaignEmailBatchJobData['recipients'][number];
+
+@Injectable()
+export class MessageCampaignBatchDeliveryService {
+ private readonly logger = new Logger(
+ MessageCampaignBatchDeliveryService.name,
+ );
+
+ constructor(
+ @InjectWorkspaceScopedRepository(CampaignDeliveryEntity)
+ private readonly campaignDeliveryRepository: WorkspaceScopedRepository<CampaignDeliveryEntity>,
+ @InjectDataSource()
+ private readonly dataSource: DataSource,
+ @InjectMessageQueue(MessageQueue.campaignSendQueue)
+ private readonly messageQueueService: MessageQueueService,
+ private readonly workspaceOrmManager: WorkspaceOrmManager,
+ private readonly emailingDomainSenderService: EmailingDomainSenderService,
+ private readonly emailBillingService: EmailBillingService,
+ private readonly campaignVariableService: CampaignVariableService,
+ private readonly messageCampaignLifecycleService: MessageCampaignLifecycleService,
+ private readonly messageCampaignStatisticsService: MessageCampaignStatisticsService,
+ private readonly campaignSendSlotService: CampaignSendSlotService,
+ ) {}
+
+ async processSendBatchJob(
+ data: SendCampaignEmailBatchJobData,
+ ): Promise<void> {
+ const { workspaceId, campaignId } = data;
+
+ await this.workspaceOrmManager.executeInWorkspaceContext(async () => {
+ const campaign =
+ await this.messageCampaignLifecycleService.findRunningCampaign(
+ campaignId,
+ );
+ const creditContext =
+ await this.emailBillingService.getEmailCreditContext(workspaceId);
+
+ const claimToken = v4();
+ const claimedDeliveryIds = await this.claimBatch({
+ workspaceId,
+ deliveryIds: data.recipients.map((recipient) => recipient.messageId),
+ claimToken,
+ });
+
+ if (claimedDeliveryIds.length === 0) {
+ return;
+ }
+
+ const claimedDeliveryIdSet = new Set(claimedDeliveryIds);
+ const claimedRecipients = data.recipients.filter((recipient) =>
+ claimedDeliveryIdSet.has(recipient.messageId),
+ );
+
+ try {
+ await this.processClaimedBatch({
+ data,
+ campaign,
+ creditContext,
+ claimToken,
+ claimedRecipients,
+ });
+ } finally {
+ await this.requeueClaimsNeverHandedToProvider({
+ workspaceId,
+ claimToken,
+ });
+ }
+
+ await this.messageCampaignStatisticsService
+ .scheduleRefresh({ workspaceId, campaignId })
+ .catch((error) => {
+ this.logger.error(
+ `Campaign ${campaignId} could not schedule a statistics refresh: ${
+ error instanceof Error ? error.message : String(error)
+ }`,
+ );
+ });
+
+ await this.messageCampaignLifecycleService.finalizeCampaignIfComplete({
+ workspaceId,
+ campaignId,
+ });
+ }, buildSystemAuthContext(workspaceId));
+ }
+
+ private async processClaimedBatch({
+ data,
+ campaign,
+ creditContext,
+ claimToken,
+ claimedRecipients,
+ }: {
+ data: SendCampaignEmailBatchJobData;
+ campaign: MessageCampaignWorkspaceEntity | null;
+ creditContext: EmailCreditContext;
+ claimToken: string;
+ claimedRecipients: BatchRecipient[];
+ }): Promise<void> {
+ const { workspaceId } = data;
+
+ if (!isDefined(campaign)) {
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ skipReason: CAMPAIGN_SKIP_REASON.CAMPAIGN_CANCELED,
+ });
+
+ return;
+ }
+
+ if (!creditContext.hasCredits) {
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ skipReason: CAMPAIGN_SKIP_REASON.OUT_OF_CREDITS,
+ });
+
+ return;
+ }
+
+ // Suppressed recipients are resolved before the slots are asked for, so a
+ // batch full of unsubscribed addresses does not spend send capacity that
+ // the recipients it actually has could have used. This only sizes the
+ // charge: the sender resolves suppression again at the handoff, and anyone
+ // who unsubscribes in between is dropped there. That leaves the batch
+ // having paid for a slot it did not use, which costs throughput rather than
+ // mailing someone who opted out.
+ const blockedAddresses =
+ await this.emailingDomainSenderService.findBlockedRecipientAddresses({
+ workspaceId,
+ sendKind: 'MARKETING',
+ emailAddresses: claimedRecipients.map((recipient) => recipient.email),
+ unsubscribeTopicId: campaign.unsubscribeTopicId ?? undefined,
+ });
+
+ const deliverableRecipientCount = claimedRecipients.filter(
+ (recipient) =>
+ !blockedAddresses.has(recipient.email.trim().toLowerCase()),
+ ).length;
+
+ const sendSlotRefusal =
+ deliverableRecipientCount === 0
+ ? null
+ : await this.campaignSendSlotService.findSendSlotRefusal({
+ workspaceId,
+ requestedSlotCount: deliverableRecipientCount,
+ });
+
+ if (isDefined(sendSlotRefusal)) {
+ await this.deferRateLimitedBatch({
+ data,
+ claimToken,
+ claimedRecipients,
+ sendSlotRefusal,
+ });
+
+ return;
+ }
+
+ const campaignStillRunning =
+ await this.messageCampaignLifecycleService.findRunningCampaign(
+ data.campaignId,
+ );
+
+ if (!isDefined(campaignStillRunning)) {
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ skipReason: CAMPAIGN_SKIP_REASON.CAMPAIGN_CANCELED,
+ });
+
+ return;
+ }
+
+ await this.deliverBatch({
+ data,
+ campaign: campaignStillRunning,
+ claimToken,
+ claimedRecipients,
+ });
+ }
+
+ private async deferRateLimitedBatch({
+ data,
+ claimToken,
+ claimedRecipients,
+ sendSlotRefusal,
+ }: {
+ data: SendCampaignEmailBatchJobData;
+ claimToken: string;
+ claimedRecipients: BatchRecipient[];
+ sendSlotRefusal: SendSlotRefusal;
+ }): Promise<void> {
+ const { workspaceId } = data;
+ const attemptCount = (data.rateLimitedAttemptCount ?? 0) + 1;
+
+ if (attemptCount > SEND_SLOT_RETRY.attemptLimit) {
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: CAMPAIGN_DELIVERY_STATE.FAILED,
+ failureReason: CAMPAIGN_FAILURE_REASON.RATE_LIMITED,
+ });
+
+ return;
+ }
+
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: CAMPAIGN_DELIVERY_STATE.QUEUED,
+ });
+
+ // A workspace whose limit is below this batch can never admit it whole, so
+ // re-queueing the same size would defer until the attempt limit and fail
+ // recipients the provider would have taken. Split it to what fits instead.
+ const chunks = chunkRecipientsToAdmissibleSize({
+ recipients: claimedRecipients,
+ limitValue: sendSlotRefusal.limitValue,
+ });
+
+ const delay = computeSendSlotBackoffMs({
+ attemptCount,
+ retryDelayMs: sendSlotRefusal.retryDelayMs,
+ windowMs: sendSlotRefusal.windowMs,
+ });
+
+ // A split batch starts its own retry budget: it was never refused at this
+ // size, and inheriting the count would fail it early.
+ const requeuedAttemptCount = chunks.length > 1 ? 0 : attemptCount;
+
+ await this.messageQueueService.bulkAdd<SendCampaignEmailBatchJobData>(
+ SEND_CAMPAIGN_EMAIL_BATCH_JOB,
+ chunks.map((chunk) => ({
+ data: {
+ ...data,
+ recipients: chunk,
+ rateLimitedAttemptCount: requeuedAttemptCount,
+ },
+ })),
+ {
+ delay,
+ retryLimit: CAMPAIGN_SEND_RETRY_LIMIT,
+ backoff: CAMPAIGN_SEND_RETRY_BACKOFF,
+ },
+ );
+ }
+
+ private async deliverBatch({
+ data,
+ campaign,
+ claimToken,
+ claimedRecipients,
+ }: {
+ data: SendCampaignEmailBatchJobData;
+ campaign: MessageCampaignWorkspaceEntity;
+ claimToken: string;
+ claimedRecipients: BatchRecipient[];
+ }): Promise<void> {
+ const { workspaceId, campaignId, emailingDomainId } = data;
+
+ const { template, variableNames } = await compileCampaignBatchTemplate({
+ subjectTemplate: campaign.subject ?? '',
+ bodyTemplate: campaign.bodyTemplate ?? '',
+ });
+
+ const personRepository = this.workspaceOrmManager.getRepository(
+ PersonWorkspaceEntity,
+ { shouldBypassPermissionChecks: true },
+ );
+
+ const people = await personRepository.find({
+ where: {
+ id: In(claimedRecipients.map((recipient) => recipient.personId)),
+ },
+ });
+ const personById = new Map(people.map((person) => [person.id, person]));
+
+ const replacementsByDeliveryId = new Map<string, Record<string, string>>();
+
+ for (const recipient of claimedRecipients) {
+ const variables =
+ await this.campaignVariableService.buildVariablesForPerson(
+ workspaceId,
+ personById.get(recipient.personId) ?? null,
+ );
+
+ replacementsByDeliveryId.set(
+ recipient.messageId,
+ buildCampaignBatchReplacements({ variableNames, variables }),
+ );
+ }
+
+ const providerOutcome = await this.emailingDomainSenderService
+ .sendEmailBatch({
+ workspaceId,
+ emailingDomainId,
+ sendKind: 'MARKETING',
+ from: campaign.fromAddress?.primaryEmail ?? '',
+ template,
+ recipients: claimedRecipients.map((recipient) => ({
+ email: recipient.email,
+ replacements: replacementsByDeliveryId.get(recipient.messageId) ?? {},
+ })),
+ unsubscribeTopicId: campaign.unsubscribeTopicId ?? undefined,
+ })
+ .catch(async (error) => {
+ const { shouldRetry } = await this.recordBatchFailure({
+ workspaceId,
+ campaignId,
+ claimToken,
+ claimedRecipients,
+ error,
+ });
+
+ if (shouldRetry) {
+ throw error;
+ }
+
+ return null;
+ });
+
+ if (!isDefined(providerOutcome)) {
+ return;
+ }
+
+ const settlements = resolveCampaignBatchSettlements({
+ claimedRecipients,
+ outcome: providerOutcome,
+ });
+
+ try {
+ await this.settleDeliveredBatch({
+ data,
+ claimToken,
+ settlements,
+ template,
+ replacementsByDeliveryId,
+ });
+ } catch (error) {
+ await this.settleClaimsAlreadyHandedToProvider({
+ workspaceId,
+ claimToken,
+ settlements,
+ });
+
+ throw error;
+ }
+ }
+
+ private async settleDeliveredBatch({
+ data,
+ claimToken,
+ settlements,
+ template,
+ replacementsByDeliveryId,
+ }: {
+ data: SendCampaignEmailBatchJobData;
+ claimToken: string;
+ settlements: CampaignDeliverySettlement[];
+ template: EmailingDomainEmailTemplate;
+ replacementsByDeliveryId: Map<string, Record<string, string>>;
+ }): Promise<void> {
+ const { workspaceId, campaignId, userWorkspaceId } = data;
+
+ const settledDeliveryIds = await this.settleClaimedBatch({
+ workspaceId,
+ claimToken,
+ settlements,
+ });
+
+ const sentSettlements = settlements.filter(
+ (settlement) =>
+ settlement.state === CAMPAIGN_DELIVERY_STATE.SENT &&
+ settledDeliveryIds.has(settlement.deliveryId) &&
+ isDefined(settlement.providerMessageId),
+ );
+
+ for (const settlement of sentSettlements) {
+ await this.recordSentMessage({
+ deliveryId: settlement.deliveryId,
+ providerMessageId: settlement.providerMessageId ?? '',
+ template,
+ replacements: replacementsByDeliveryId.get(settlement.deliveryId) ?? {},
+ });
+ }
+
+ const sentDeliveryIds = sentSettlements.map(
+ (settlement) => settlement.deliveryId,
+ );
+
+ await this.emailBillingService
+ .billSentEmails({
+ workspaceId,
+ sentEmailCount: sentDeliveryIds.length,
+ userWorkspaceId,
+ })
+ .catch((error) => {
+ this.logger.error(
+ `Campaign ${campaignId} delivered ${sentDeliveryIds.length} message(s) but failed to bill them: ${
+ error instanceof Error ? error.message : String(error)
+ }`,
+ );
+ });
+ }
+
+ private async recordSentMessage({
+ deliveryId,
+ providerMessageId,
+ template,
+ replacements,
+ }: {
+ deliveryId: string;
+ providerMessageId: string;
+ template: EmailingDomainEmailTemplate;
+ replacements: Record<string, string>;
+ }): Promise<void> {
+ const messageRepository = this.workspaceOrmManager.getRepository(
+ MessageWorkspaceEntity,
+ { shouldBypassPermissionChecks: true },
+ SKIP_EVENT_EMISSION,
+ );
+
+ await messageRepository.update(deliveryId, {
+ headerMessageId: providerMessageId,
+ subject: applyReplacementTags(template.subject, replacements),
+ text: applyReplacementTags(template.text, replacements),
+ });
+
+ const associationRepository = this.workspaceOrmManager.getRepository(
+ MessageChannelMessageAssociationWorkspaceEntity,
+ { shouldBypassPermissionChecks: true },
+ SKIP_EVENT_EMISSION,
+ );
+
+ await associationRepository.update(
+ { messageId: deliveryId },
+ {
+ messageExternalId: providerMessageId,
+ messageThreadExternalId: providerMessageId,
+ },
+ );
+ }
+
+ private async recordBatchFailure({
+ workspaceId,
+ campaignId,
+ claimToken,
+ claimedRecipients,
+ error,
+ }: {
+ workspaceId: string;
+ campaignId: string;
+ claimToken: string;
+ claimedRecipients: BatchRecipient[];
+ error: unknown;
+ }): Promise<{ shouldRetry: boolean }> {
+ const { state, skipReason, failureReason, shouldRetry } =
+ resolveCampaignSendFailure(error);
+
+ await this.settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients: claimedRecipients,
+ state: shouldRetry ? CAMPAIGN_DELIVERY_STATE.QUEUED : state,
+ skipReason,
+ failureReason,
+ });
+
+ this.logger.warn(
+ `Campaign ${campaignId} batch of ${claimedRecipients.length} failed: ${
+ error instanceof Error ? error.message : String(error)
+ }`,
+ );
+
+ return { shouldRetry };
+ }
+
+ private async claimBatch({
+ workspaceId,
+ deliveryIds,
+ claimToken,
+ }: {
+ workspaceId: string;
+ deliveryIds: string[];
+ claimToken: string;
+ }): Promise<string[]> {
+ const { raw } = await this.campaignDeliveryRepository
+ .createQueryBuilder()
+ .update()
+ .set({
+ state: CAMPAIGN_DELIVERY_STATE.SENDING,
+ claimToken,
+ claimExpiresAt: new Date(Date.now() + CAMPAIGN_DELIVERY_CLAIM_TTL_MS),
+ })
+ .where('"workspaceId" = :workspaceId', { workspaceId })
+ .andWhere('id IN (:...deliveryIds)', { deliveryIds })
+ .andWhere('state IN (:...claimableStates)', {
+ claimableStates: CLAIMABLE_CAMPAIGN_DELIVERY_STATES,
+ })
+ .returning(['id'])
+ .execute();
+
+ return (raw as { id: string }[]).map((row) => row.id);
+ }
+
+ private async settleWholeBatchAs({
+ workspaceId,
+ claimToken,
+ recipients,
+ state,
+ skipReason = null,
+ failureReason = null,
+ }: {
+ workspaceId: string;
+ claimToken: string;
+ recipients: BatchRecipient[];
+ state: CampaignDeliveryEntity['state'];
+ skipReason?: CampaignDeliveryEntity['skipReason'];
+ failureReason?: CampaignDeliveryEntity['failureReason'];
+ }): Promise<void> {
+ if (recipients.length === 0) {
+ return;
+ }
+
+ await this.campaignDeliveryRepository.update(
+ workspaceId,
+ {
+ id: In(recipients.map((recipient) => recipient.messageId)),
+ claimToken,
+ },
+ {
+ state,
+ skipReason,
+ failureReason,
+ claimToken: null,
+ claimExpiresAt: null,
+ },
+ );
+ }
+
+ private async settleClaimedBatch({
+ workspaceId,
+ claimToken,
+ settlements,
+ }: {
+ workspaceId: string;
+ claimToken: string;
+ settlements: CampaignDeliverySettlement[];
+ }): Promise<Set<string>> {
+ if (settlements.length === 0) {
+ return new Set();
+ }
+
+ const { sql, parameters } = buildCampaignDeliverySettleQuery({
+ workspaceId,
+ claimToken,
+ settlements,
+ });
+
+ const settledRows: { id: string }[] = await this.dataSource.query(
+ sql,
+ parameters,
+ );
+
+ return new Set(settledRows.map((row) => row.id));
+ }
+
+ private async requeueClaimsNeverHandedToProvider({
+ workspaceId,
+ claimToken,
+ }: {
+ workspaceId: string;
+ claimToken: string;
+ }): Promise<void> {
+ await this.campaignDeliveryRepository.update(
+ workspaceId,
+ { claimToken },
+ {
+ state: CAMPAIGN_DELIVERY_STATE.QUEUED,
+ claimToken: null,
+ claimExpiresAt: null,
+ },
+ );
+ }
+
+ // Settling threw after the provider had already taken the batch, so the rows
+ // still hold their claim. The rows the provider accepted are settled first:
+ // whatever is left claimed after this is re-queued by the finally block, and
+ // only recipients the provider never delivered to may safely go back.
+ private async settleClaimsAlreadyHandedToProvider({
+ workspaceId,
+ claimToken,
+ settlements,
+ }: {
+ workspaceId: string;
+ claimToken: string;
+ settlements: CampaignDeliverySettlement[];
+ }): Promise<void> {
+ const isAcceptedByProvider = (settlement: CampaignDeliverySettlement) =>
+ settlement.state === CAMPAIGN_DELIVERY_STATE.SENT;
+
+ // Keeps the provider message id, which is what later delivery and bounce
+ // webhooks match on; the reason records that billing and the message rows
+ // never ran for them.
+ await this.settleClaimedBatch({
+ workspaceId,
+ claimToken,
+ settlements: settlements
+ .filter(isAcceptedByProvider)
+ .map((settlement) => ({
+ ...settlement,
+ failureReason: CAMPAIGN_FAILURE_REASON.SETTLEMENT_LOST,
+ })),
+ });
+
+ await this.settleClaimedBatch({
+ workspaceId,
+ claimToken,
+ settlements: settlements.filter(
+ (settlement) => !isAcceptedByProvider(settlement),
+ ),
+ });
+ }
+}
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-delivery.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-delivery.service.ts
index 2a08f2fba87..8a1d2ba0527 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-delivery.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-delivery.service.ts
@@ -7,17 +7,13 @@ import { SEND_CAMPAIGN_EMAIL_JOB } from 'src/engine/core-modules/emailing-domain
import { CLAIMABLE_CAMPAIGN_DELIVERY_STATES } from 'src/engine/core-modules/emailing-domain/constants/claimable-campaign-delivery-states.constant';
import { CAMPAIGN_SEND_RETRY_BACKOFF } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-retry-backoff.constant';
import { CAMPAIGN_SEND_RETRY_LIMIT } from 'src/engine/core-modules/emailing-domain/constants/campaign-send-retry-limit.constant';
+import { SEND_SLOT_RETRY } from 'src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant';
+import { type SendSlotRefusal } from 'src/engine/core-modules/emailing-domain/types/send-slot-refusal.type';
+import { computeSendSlotBackoffMs } from 'src/modules/emailing/utils/compute-send-slot-backoff-ms.util';
import { CAMPAIGN_DELIVERY_CLAIM_TTL_MS } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-claim-ttl-ms.constant';
import { InjectMessageQueue } from 'src/engine/core-modules/message-queue/decorators/message-queue.decorator';
import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
import { MessageQueueService } from 'src/engine/core-modules/message-queue/services/message-queue.service';
-import {
- UsageLimitException,
- UsageLimitExceptionCode,
-} from 'src/engine/core-modules/usage-limit/exceptions/usage-limit.exception';
-import { UsageLimitSpeedService } from 'src/engine/core-modules/usage-limit/services/usage-limit-speed.service';
-import { UsageOperationType } from 'src/engine/core-modules/usage/enums/usage-operation-type.enum';
-import { UsageResourceType } from 'src/engine/core-modules/usage/enums/usage-resource-type.enum';
import { CAMPAIGN_DELIVERY_STATE } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-state.constant';
import { CAMPAIGN_FAILURE_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant';
import { CAMPAIGN_SKIP_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-skip-reason.constant';
@@ -30,6 +26,8 @@ import { type SendCampaignEmailJobData } from 'src/engine/core-modules/emailing-
import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
import { type WorkspaceRepository } from 'src/engine/twenty-orm/repository/workspace-repository';
import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
+import { SKIP_EVENT_EMISSION } from 'src/modules/emailing/constants/skip-event-emission.constant';
+import { CampaignSendSlotService } from 'src/modules/emailing/services/campaign-send-slot.service';
import { CampaignVariableService } from 'src/modules/emailing/services/campaign-variable.service';
import { EmailBillingService } from 'src/modules/emailing/services/email-billing.service';
import { type EmailCreditContext } from 'src/modules/emailing/types/email-credit-context.type';
@@ -51,16 +49,6 @@ type SendContext = {
claimToken: string;
};
-const SEND_SLOT_RETRY = {
- attemptLimit: 60,
- jitterRatio: 0.5,
- maxWindows: 3,
- minDelayMs: 1_000,
- maxDelayMs: 60_000,
-};
-
-type SendSlotRefusal = { retryDelayMs: number; windowMs: number };
-
@Injectable()
export class MessageCampaignDeliveryService {
private readonly logger = new Logger(MessageCampaignDeliveryService.name);
@@ -74,7 +62,7 @@ export class MessageCampaignDeliveryService {
private readonly campaignVariableService: CampaignVariableService,
private readonly messageCampaignLifecycleService: MessageCampaignLifecycleService,
private readonly messageCampaignStatisticsService: MessageCampaignStatisticsService,
- private readonly usageLimitSpeedService: UsageLimitSpeedService,
+ private readonly campaignSendSlotService: CampaignSendSlotService,
@InjectMessageQueue(MessageQueue.campaignQueue)
private readonly messageQueueService: MessageQueueService,
) {}
@@ -83,12 +71,6 @@ export class MessageCampaignDeliveryService {
const { workspaceId, campaignId } = data;
await this.workspaceOrmManager.executeInWorkspaceContext(async () => {
- const campaign = await this.findRunningCampaign(campaignId);
-
- if (!isDefined(campaign)) {
- return;
- }
-
const isStillClaimable = await this.campaignDeliveryRepository.existsBy(
workspaceId,
{
@@ -105,7 +87,9 @@ export class MessageCampaignDeliveryService {
await this.emailBillingService.getEmailCreditContext(workspaceId);
if (creditContext.hasCredits) {
- const refusal = await this.findSendSlotRefusal(workspaceId);
+ const refusal = await this.campaignSendSlotService.findSendSlotRefusal({
+ workspaceId,
+ });
if (isDefined(refusal)) {
await this.requeueRateLimitedSendJob({ data, refusal });
@@ -114,9 +98,19 @@ export class MessageCampaignDeliveryService {
}
}
+ const campaign =
+ await this.messageCampaignLifecycleService.findRunningCampaign(
+ campaignId,
+ );
+
+ if (!isDefined(campaign)) {
+ return;
+ }
+
const messageRepository = this.workspaceOrmManager.getRepository(
MessageWorkspaceEntity,
{ shouldBypassPermissionChecks: true },
+ SKIP_EVENT_EMISSION,
);
const sendContext = await this.loadSendContext({ data, campaign });
@@ -149,60 +143,6 @@ export class MessageCampaignDeliveryService {
}, buildSystemAuthContext(workspaceId));
}
- private async findRunningCampaign(
- campaignId: string,
- ): Promise<MessageCampaignWorkspaceEntity | null> {
- const campaignRepository = this.workspaceOrmManager.getRepository(
- MessageCampaignWorkspaceEntity,
- { shouldBypassPermissionChecks: true },
- );
-
- const campaign = await campaignRepository.findOne({
- where: { id: campaignId },
- });
-
- if (
- !isDefined(campaign) ||
- campaign.status === MessageCampaignStatus.CANCELED
- ) {
- return null;
- }
-
- return campaign;
- }
-
- private async findSendSlotRefusal(
- workspaceId: string,
- ): Promise<SendSlotRefusal | null> {
- try {
- await this.usageLimitSpeedService.consumeOrThrow({
- resourceType: UsageResourceType.EMAIL,
- operationType: UsageOperationType.EMAIL_SEND,
- authContext: buildSystemAuthContext(workspaceId),
- });
-
- return null;
- } catch (error) {
- if (
- !(error instanceof UsageLimitException) ||
- error.code !== UsageLimitExceptionCode.RATE_LIMITED
- ) {
- throw error;
- }
-
- return {
- retryDelayMs: Math.max(
- error.exhaustedScope?.retryAfterMs ?? 0,
- SEND_SLOT_RETRY.minDelayMs,
- ),
- windowMs:
- error.exhaustedScope?.periodUnit === 'second'
- ? (error.exhaustedScope.periodCount ?? 0) * 1000
- : 0,
- };
- }
- }
-
private async requeueRateLimitedSendJob({
data,
refusal: { retryDelayMs, windowMs },
@@ -222,23 +162,15 @@ export class MessageCampaignDeliveryService {
return;
}
- const backoffCeilingMs = Math.min(
- windowMs * SEND_SLOT_RETRY.maxWindows,
- SEND_SLOT_RETRY.maxDelayMs,
- );
-
- const backoffMs = Math.min(
- retryDelayMs * 2 ** (attemptCount - 1),
- Math.max(backoffCeilingMs, SEND_SLOT_RETRY.minDelayMs),
- );
-
await this.messageQueueService.add<SendCampaignEmailJobData>(
SEND_CAMPAIGN_EMAIL_JOB,
{ ...data, rateLimitedAttemptCount: attemptCount },
{
- delay: Math.ceil(
- backoffMs * (1 + Math.random() * SEND_SLOT_RETRY.jitterRatio),
- ),
+ delay: computeSendSlotBackoffMs({
+ attemptCount,
+ retryDelayMs,
+ windowMs,
+ }),
retryLimit: CAMPAIGN_SEND_RETRY_LIMIT,
backoff: CAMPAIGN_SEND_RETRY_BACKOFF,
},
@@ -455,6 +387,7 @@ export class MessageCampaignDeliveryService {
const associationRepository = this.workspaceOrmManager.getRepository(
MessageChannelMessageAssociationWorkspaceEntity,
{ shouldBypassPermissionChecks: true },
+ SKIP_EVENT_EMISSION,
);
await associationRepository.update(
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-lifecycle.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-lifecycle.service.ts
index c1cab0146ef..595ff8c75b0 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-lifecycle.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-lifecycle.service.ts
@@ -8,7 +8,7 @@ import { CAMPAIGN_SKIP_REASON } from 'src/engine/core-modules/emailing-domain/co
import { InjectWorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/inject-workspace-scoped-repository.decorator';
import { WorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scoped-repository/workspace-scoped-repository';
-import { type FindOptionsWhere, In, LessThan } from 'typeorm';
+import { type FindOptionsWhere, In, IsNull, LessThan } from 'typeorm';
import {
EmailingDomainException,
@@ -68,6 +68,30 @@ export class MessageCampaignLifecycleService {
);
}
+ // Returns null once the campaign is gone or canceled, which is how the send
+ // paths stop working a campaign they already claimed rows for.
+ async findRunningCampaign(
+ campaignId: string,
+ ): Promise<MessageCampaignWorkspaceEntity | null> {
+ const campaignRepository = this.workspaceOrmManager.getRepository(
+ MessageCampaignWorkspaceEntity,
+ { shouldBypassPermissionChecks: true },
+ );
+
+ const campaign = await campaignRepository.findOne({
+ where: { id: campaignId },
+ });
+
+ if (
+ !isDefined(campaign) ||
+ campaign.status === MessageCampaignStatus.CANCELED
+ ) {
+ return null;
+ }
+
+ return campaign;
+ }
+
async cancelCampaignOrThrow({
workspaceId,
userWorkspaceId,
@@ -117,6 +141,39 @@ export class MessageCampaignLifecycleService {
return { campaignId, canceledMessageCount };
}
+ // A campaign whose send jobs were lost keeps rows QUEUED forever, and QUEUED
+ // counts as unfinished, so the campaign would sit in SENDING with nothing
+ // left to move it. Failing them lets it terminalise and names why.
+ //
+ // untouchedSince separates an abandoned row from a live one: anything still
+ // being worked is claimed, deferred or settled, and each of those writes it.
+ async failOrphanedQueuedDeliveries({
+ workspaceId,
+ campaignId,
+ untouchedSince,
+ }: {
+ workspaceId: string;
+ campaignId: string;
+ untouchedSince: Date;
+ }): Promise<number> {
+ return this.settleDeliveries({
+ workspaceId,
+ criteria: {
+ campaignId,
+ state: CAMPAIGN_DELIVERY_STATE.QUEUED,
+ sentAt: IsNull(),
+ providerMessageId: IsNull(),
+ updatedAt: LessThan(untouchedSince),
+ },
+ update: {
+ state: CAMPAIGN_DELIVERY_STATE.FAILED,
+ failureReason: CAMPAIGN_FAILURE_REASON.ORPHANED,
+ claimToken: null,
+ claimExpiresAt: null,
+ },
+ });
+ }
+
async failDeliveriesWithExpiredClaims({
workspaceId,
campaignId,
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-materialization.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-materialization.service.ts
index 9d56f962a6b..636fc596cdb 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-materialization.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-materialization.service.ts
@@ -11,18 +11,19 @@ import chunk from 'lodash.chunk';
import { In, type ObjectLiteral } from 'typeorm';
import { v4 } from 'uuid';
-import {
- MATERIALIZE_CAMPAIGN_CHUNK_JOB,
- SEND_CAMPAIGN_EMAIL_JOB,
-} from 'src/engine/core-modules/emailing-domain/constants/campaign.constant';
+import { MATERIALIZE_CAMPAIGN_CHUNK_JOB } from 'src/engine/core-modules/emailing-domain/constants/campaign.constant';
+import { SEND_CAMPAIGN_EMAIL_BATCH_JOB } from 'src/engine/core-modules/emailing-domain/constants/send-campaign-email-batch-job.constant';
+import { resolveCampaignSendBatchSize } from 'src/engine/core-modules/emailing-domain/utils/resolve-campaign-send-batch-size.util';
import { type MaterializeCampaignChunkJobData } from 'src/engine/core-modules/emailing-domain/types/materialize-campaign-chunk-job-data.type';
import { type MaterializeCampaignJobData } from 'src/engine/core-modules/emailing-domain/types/materialize-campaign-job-data.type';
-import { type SendCampaignEmailJobData } from 'src/engine/core-modules/emailing-domain/types/send-campaign-email-job-data.type';
+import { type SendCampaignEmailBatchJobData } from 'src/engine/core-modules/emailing-domain/types/send-campaign-email-batch-job-data.type';
import { InjectMessageQueue } from 'src/engine/core-modules/message-queue/decorators/message-queue.decorator';
import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';
import { MessageQueueService } from 'src/engine/core-modules/message-queue/services/message-queue.service';
+import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';
import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
+import { SKIP_EVENT_EMISSION } from 'src/modules/emailing/constants/skip-event-emission.constant';
import { MessageCampaignLifecycleService } from 'src/modules/emailing/services/message-campaign-lifecycle.service';
import { MessageCampaignWorkspaceEntity } from 'src/modules/emailing/standard-objects/message-campaign.workspace-entity';
import { type CampaignRecipient } from 'src/engine/core-modules/emailing-domain/types/campaign-recipient.type';
@@ -42,11 +43,6 @@ import { isDefined } from 'twenty-shared/utils';
const MATERIALIZATION_CHUNK_SIZE = 500;
-// Campaign rows are machine-generated and nothing subscribes to them: no
-// webhook, workflow trigger or timeline activity. Emitting would cost a
-// snapshot SELECT of every row written plus a timeline row per recipient.
-const SKIP_EVENT_EMISSION = { shouldSkipEventEmission: true };
-
type CampaignMessageRow = {
recipient: CampaignMessageRecipient;
messageId: string;
@@ -63,6 +59,9 @@ export class MessageCampaignMaterializationService {
private readonly messageCampaignLifecycleService: MessageCampaignLifecycleService,
@InjectMessageQueue(MessageQueue.campaignQueue)
private readonly messageQueueService: MessageQueueService,
+ @InjectMessageQueue(MessageQueue.campaignSendQueue)
+ private readonly campaignSendQueueService: MessageQueueService,
+ private readonly twentyConfigService: TwentyConfigService,
) {}
async processMaterializeJob({
@@ -225,8 +224,7 @@ export class MessageCampaignMaterializationService {
null,
);
- await this.insertMessagesBeforeTheirDeliveries({
- workspaceId,
+ await this.insertCampaignMessages({
campaignId,
messageChannelId,
fromAddress: campaign.fromAddress?.primaryEmail ?? '',
@@ -240,6 +238,16 @@ export class MessageCampaignMaterializationService {
});
}
+ // Driven by the whole chunk rather than by the recipients that still
+ // needed message rows: a retry after a failed upsert sees their messages
+ // already materialized, and those recipients would otherwise never get a
+ // delivery row and never be sent.
+ await this.upsertQueuedDeliveries({
+ workspaceId,
+ campaignId,
+ recipients,
+ });
+
await this.enqueueSendJobs({
workspaceId,
campaignId,
@@ -335,17 +343,23 @@ export class MessageCampaignMaterializationService {
return;
}
- await this.messageQueueService.bulkAdd<SendCampaignEmailJobData>(
- SEND_CAMPAIGN_EMAIL_JOB,
- recipients.map((recipient) => ({
+ const batchSize = resolveCampaignSendBatchSize(
+ this.twentyConfigService.get('EMAIL_SEND_RATE_LIMITING_LIMIT'),
+ );
+
+ await this.campaignSendQueueService.bulkAdd<SendCampaignEmailBatchJobData>(
+ SEND_CAMPAIGN_EMAIL_BATCH_JOB,
+ chunk(recipients, batchSize).map((batch) => ({
data: {
workspaceId,
campaignId,
- messageId: recipient.messageId,
- personId: recipient.personId,
- recipientEmail: recipient.email,
emailingDomainId,
userWorkspaceId,
+ recipients: batch.map((recipient) => ({
+ messageId: recipient.messageId,
+ personId: recipient.personId,
+ email: recipient.email,
+ })),
},
})),
{
@@ -355,8 +369,7 @@ export class MessageCampaignMaterializationService {
);
}
- private async insertMessagesBeforeTheirDeliveries({
- workspaceId,
+ private async insertCampaignMessages({
campaignId,
messageChannelId,
fromAddress,
@@ -365,7 +378,6 @@ export class MessageCampaignMaterializationService {
now,
recipients,
}: {
- workspaceId: string;
campaignId: string;
messageChannelId: string;
fromAddress: string;
@@ -388,6 +400,20 @@ export class MessageCampaignMaterializationService {
temporaryExternalId: v4(),
})),
});
+ }
+
+ private async upsertQueuedDeliveries({
+ workspaceId,
+ campaignId,
+ recipients,
+ }: {
+ workspaceId: string;
+ campaignId: string;
+ recipients: CampaignMessageRecipient[];
+ }): Promise<void> {
+ if (recipients.length === 0) {
+ return;
+ }
await this.campaignDeliveryRepository.upsert(
workspaceId,
diff --git a/packages/twenty-server/src/modules/emailing/services/message-campaign-recovery.service.ts b/packages/twenty-server/src/modules/emailing/services/message-campaign-recovery.service.ts
index 3139dc7f722..e87479c3252 100644
--- a/packages/twenty-server/src/modules/emailing/services/message-campaign-recovery.service.ts
+++ b/packages/twenty-server/src/modules/emailing/services/message-campaign-recovery.service.ts
@@ -12,6 +12,13 @@ import { MessageWorkspaceEntity } from 'src/modules/messaging/common/standard-ob
const SENDING_STALE_THRESHOLD_MS = 60 * 60 * 1000;
+// Must exceed the longest a live row can legitimately sit untouched: a batch
+// deferred by the rate limiter re-queues its rows for up to
+// SEND_SLOT_RETRY.attemptLimit backoffs of maxDelayMs, and a backed-up queue or
+// a worker outage holds rows that were never claimed at all. Being wrong here
+// fails recipients whose jobs were still coming.
+const ORPHANED_QUEUED_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+
@Injectable()
export class MessageCampaignRecoveryService {
private readonly logger = new Logger(MessageCampaignRecoveryService.name);
@@ -127,6 +134,23 @@ export class MessageCampaignRecoveryService {
);
}
+ const orphanedCount =
+ await this.messageCampaignLifecycleService.failOrphanedQueuedDeliveries(
+ {
+ workspaceId,
+ campaignId,
+ untouchedSince: new Date(
+ Date.now() - ORPHANED_QUEUED_THRESHOLD_MS,
+ ),
+ },
+ );
+
+ if (orphanedCount > 0) {
+ this.logger.warn(
+ `Campaign ${campaignId} of workspace ${workspaceId} had ${orphanedCount} message(s) queued with no send job left and they were failed`,
+ );
+ }
+
await this.messageCampaignLifecycleService.finalizeCampaignIfComplete({
workspaceId,
campaignId,
diff --git a/packages/twenty-server/src/modules/emailing/types/campaign-batch-send-outcome.type.ts b/packages/twenty-server/src/modules/emailing/types/campaign-batch-send-outcome.type.ts
new file mode 100644
index 00000000000..c576b1fe732
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/types/campaign-batch-send-outcome.type.ts
@@ -0,0 +1,8 @@
+export type CampaignBatchSendOutcome = {
+ entries: {
+ recipientIndex: number;
+ messageId: string | null;
+ errorMessage: string | null;
+ }[];
+ suppressedRecipientIndexes: number[];
+};
diff --git a/packages/twenty-server/src/modules/emailing/types/campaign-delivery-settlement.type.ts b/packages/twenty-server/src/modules/emailing/types/campaign-delivery-settlement.type.ts
new file mode 100644
index 00000000000..37d03f90ec2
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/types/campaign-delivery-settlement.type.ts
@@ -0,0 +1,6 @@
+import { type CampaignDeliveryEntity } from 'src/engine/core-modules/emailing-domain/campaign-delivery.entity';
+
+export type CampaignDeliverySettlement = Pick<
+ CampaignDeliveryEntity,
+ 'state' | 'skipReason' | 'failureReason' | 'providerMessageId' | 'sentAt'
+> & { deliveryId: string };
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts
new file mode 100644
index 00000000000..99c79fb902a
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-batch-replacements.util.spec.ts
@@ -0,0 +1,98 @@
+import { applyReplacementTags } from 'src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util';
+import { buildCampaignBatchReplacements } from 'src/modules/emailing/utils/build-campaign-batch-replacements.util';
+
+describe('buildCampaignBatchReplacements', () => {
+ it('escapes a value for the html body and leaves it raw for the text body', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['name.firstName'],
+ variables: { 'name.firstName': '<img onerror="x">' },
+ });
+
+ expect(applyReplacementTags('Hello {{v_h_0}}', replacements)).toBe(
+ 'Hello &lt;img onerror=&quot;x&quot;&gt;',
+ );
+ expect(applyReplacementTags('Hello {{v_t_0}}', replacements)).toBe(
+ 'Hello <img onerror="x">',
+ );
+ });
+
+ it('percent-encodes a value destined for a url so it cannot leave its attribute', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['name.firstName'],
+ variables: { 'name.firstName': '" onmouseover="alert(1)' },
+ });
+
+ expect(
+ applyReplacementTags(
+ '<a href="https://x.com/{{v_u_0}}">go</a>',
+ replacements,
+ ),
+ ).toBe('<a href="https://x.com/%22%20onmouseover%3D%22alert(1)">go</a>');
+ });
+
+ it('strips the scheme separator from a url value so it cannot become executable', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['website'],
+ variables: { website: 'javascript:alert(1)' },
+ });
+
+ expect(applyReplacementTags('{{v_u_0}}', replacements)).toBe(
+ 'javascript%3Aalert(1)',
+ );
+ });
+
+ it('substitutes an empty string for a variable the recipient has no value for', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['jobTitle'],
+ variables: {},
+ });
+
+ expect(applyReplacementTags('Role: {{v_t_0}}.', replacements)).toBe(
+ 'Role: .',
+ );
+ });
+
+ it('keeps each variable on its own pair of tags', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['first', 'second'],
+ variables: { first: 'Ada', second: 'Lovelace' },
+ });
+
+ expect(applyReplacementTags('{{v_t_0}} {{v_t_1}}', replacements)).toBe(
+ 'Ada Lovelace',
+ );
+ });
+
+ it('leaves a tag the recipient has no replacement for untouched rather than blanking it', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['known'],
+ variables: { known: 'yes' },
+ });
+
+ expect(applyReplacementTags('{{v_t_0}} {{v_t_9}}', replacements)).toBe(
+ 'yes {{v_t_9}}',
+ );
+ });
+});
+
+describe('inherited object properties', () => {
+ it('treats a variable named after an Object prototype member as absent rather than its function', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['toString'],
+ variables: {},
+ });
+
+ expect(applyReplacementTags('Hi {{v_t_0}}.', replacements)).toBe('Hi .');
+ });
+
+ it('leaves a prototype-named tag untouched instead of resolving it off Object.prototype', () => {
+ const replacements = buildCampaignBatchReplacements({
+ variableNames: ['known'],
+ variables: { known: 'yes' },
+ });
+
+ expect(
+ applyReplacementTags('{{constructor}} {{v_t_0}}', replacements),
+ ).toBe('{{constructor}} yes');
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-delivery-settle-query.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-delivery-settle-query.util.spec.ts
new file mode 100644
index 00000000000..f97f057691a
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-delivery-settle-query.util.spec.ts
@@ -0,0 +1,113 @@
+import { CAMPAIGN_DELIVERY_STATE } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-state.constant';
+import { CAMPAIGN_SKIP_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-skip-reason.constant';
+import { type CampaignDeliverySettlement } from 'src/modules/emailing/types/campaign-delivery-settlement.type';
+import { buildCampaignDeliverySettleQuery } from 'src/modules/emailing/utils/build-campaign-delivery-settle-query.util';
+
+const SENT_AT = new Date('2026-01-01T00:00:00.000Z');
+
+const buildSettlement = (
+ overrides: Partial<CampaignDeliverySettlement> & { deliveryId: string },
+): CampaignDeliverySettlement => ({
+ state: CAMPAIGN_DELIVERY_STATE.SENT,
+ skipReason: null,
+ failureReason: null,
+ providerMessageId: null,
+ sentAt: null,
+ ...overrides,
+});
+
+describe('buildCampaignDeliverySettleQuery', () => {
+ it('keeps every settlement on its own row across the parallel arrays', () => {
+ const { parameters } = buildCampaignDeliverySettleQuery({
+ workspaceId: 'workspace-1',
+ claimToken: 'claim-1',
+ settlements: [
+ buildSettlement({
+ deliveryId: 'delivery-a',
+ providerMessageId: 'provider-a',
+ sentAt: SENT_AT,
+ }),
+ buildSettlement({
+ deliveryId: 'delivery-b',
+ state: CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ skipReason: CAMPAIGN_SKIP_REASON.SUPPRESSED,
+ }),
+ ],
+ });
+
+ const [
+ deliveryIds,
+ states,
+ skipReasons,
+ failureReasons,
+ providerMessageIds,
+ sentAtValues,
+ ] = parameters;
+
+ expect(deliveryIds).toEqual(['delivery-a', 'delivery-b']);
+ expect(states).toEqual([
+ CAMPAIGN_DELIVERY_STATE.SENT,
+ CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ ]);
+ expect(skipReasons).toEqual([null, CAMPAIGN_SKIP_REASON.SUPPRESSED]);
+ expect(failureReasons).toEqual([null, null]);
+ expect(providerMessageIds).toEqual(['provider-a', null]);
+ expect(sentAtValues).toEqual([SENT_AT, null]);
+ });
+
+ it('settles two people who share an email address as two separate deliveries', () => {
+ const { parameters } = buildCampaignDeliverySettleQuery({
+ workspaceId: 'workspace-1',
+ claimToken: 'claim-1',
+ settlements: [
+ buildSettlement({
+ deliveryId: 'delivery-first',
+ providerMessageId: 'provider-first',
+ sentAt: SENT_AT,
+ }),
+ buildSettlement({
+ deliveryId: 'delivery-second',
+ providerMessageId: 'provider-second',
+ sentAt: SENT_AT,
+ }),
+ ],
+ });
+
+ expect(parameters[0]).toEqual(['delivery-first', 'delivery-second']);
+ expect(parameters[4]).toEqual(['provider-first', 'provider-second']);
+ });
+
+ it('scopes the update to the workspace and the claim that is being settled', () => {
+ const { sql, parameters } = buildCampaignDeliverySettleQuery({
+ workspaceId: 'workspace-1',
+ claimToken: 'claim-1',
+ settlements: [buildSettlement({ deliveryId: 'delivery-a' })],
+ });
+
+ expect(sql).toContain('delivery."workspaceId" = $7');
+ expect(sql).toContain('delivery."claimToken" = $8');
+ expect(parameters[6]).toBe('workspace-1');
+ expect(parameters[7]).toBe('claim-1');
+ });
+
+ it('returns the settled ids from a select so the driver reports rows rather than an update tuple', () => {
+ const { sql } = buildCampaignDeliverySettleQuery({
+ workspaceId: 'workspace-1',
+ claimToken: 'claim-1',
+ settlements: [buildSettlement({ deliveryId: 'delivery-a' })],
+ });
+
+ expect(sql.trim().startsWith('WITH settled AS (')).toBe(true);
+ expect(sql).toContain('SELECT "id" FROM settled');
+ });
+
+ it('advances updatedAt so staleness checks see the settle', () => {
+ const { sql } = buildCampaignDeliverySettleQuery({
+ workspaceId: 'workspace-1',
+ claimToken: 'claim-1',
+ settlements: [buildSettlement({ deliveryId: 'delivery-a' })],
+ });
+
+ expect(sql).toContain('"updatedAt" = now()');
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/chunk-recipients-to-admissible-size.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/chunk-recipients-to-admissible-size.util.spec.ts
new file mode 100644
index 00000000000..86be0ec86f0
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/chunk-recipients-to-admissible-size.util.spec.ts
@@ -0,0 +1,48 @@
+import { chunkRecipientsToAdmissibleSize } from 'src/modules/emailing/utils/chunk-recipients-to-admissible-size.util';
+
+describe('chunkRecipientsToAdmissibleSize', () => {
+ it('keeps the batch whole when it already fits the limit', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({
+ recipients: [1, 2, 3],
+ limitValue: 10,
+ }),
+ ).toEqual([[1, 2, 3]]);
+ });
+
+ it('splits a batch the limit can never admit whole', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({
+ recipients: [1, 2, 3, 4, 5],
+ limitValue: 2,
+ }),
+ ).toEqual([[1, 2], [3, 4], [5]]);
+ });
+
+ it('splits to single sends when only one slot per window is allowed', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({ recipients: [1, 2], limitValue: 1 }),
+ ).toEqual([[1], [2]]);
+ });
+
+ it('keeps the batch whole when the limit is unknown', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({ recipients: [1, 2], limitValue: null }),
+ ).toEqual([[1, 2]]);
+ });
+
+ it('keeps the batch whole rather than looping forever on a zero limit', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({ recipients: [1, 2], limitValue: 0 }),
+ ).toEqual([[1, 2]]);
+ });
+
+ it('rounds a fractional limit down to whole recipients', () => {
+ expect(
+ chunkRecipientsToAdmissibleSize({
+ recipients: [1, 2, 3],
+ limitValue: 2.7,
+ }),
+ ).toEqual([[1, 2], [3]]);
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts
new file mode 100644
index 00000000000..8038d97d863
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/compile-campaign-batch-template.util.spec.ts
@@ -0,0 +1,129 @@
+import { EMAIL_DOCUMENT_SCHEMA_VERSION } from 'twenty-shared/utils';
+
+import { applyReplacementTags } from 'src/engine/core-modules/emailing-domain/utils/apply-replacement-tags.util';
+import { buildCampaignBatchReplacements } from 'src/modules/emailing/utils/build-campaign-batch-replacements.util';
+import { compileCampaignBatchTemplate } from 'src/modules/emailing/utils/compile-campaign-batch-template.util';
+
+const serializeDocument = (content: unknown[]): string =>
+ JSON.stringify({
+ type: 'doc',
+ attrs: { schemaVersion: EMAIL_DOCUMENT_SCHEMA_VERSION },
+ content,
+ });
+
+const paragraphDocument = (text: string): string =>
+ serializeDocument([{ type: 'paragraph', content: [{ type: 'text', text }] }]);
+
+const deliverToRecipient = async ({
+ subjectTemplate = 'Newsletter',
+ bodyTemplate,
+ variables,
+}: {
+ subjectTemplate?: string;
+ bodyTemplate: string;
+ variables: Record<string, string>;
+}) => {
+ const { template, variableNames } = await compileCampaignBatchTemplate({
+ subjectTemplate,
+ bodyTemplate,
+ });
+ const replacements = buildCampaignBatchReplacements({
+ variableNames,
+ variables,
+ });
+
+ return {
+ variableNames,
+ subject: applyReplacementTags(template.subject, replacements),
+ html: applyReplacementTags(template.html ?? '', replacements),
+ text: applyReplacementTags(template.text, replacements),
+ };
+};
+
+describe('compileCampaignBatchTemplate', () => {
+ beforeAll(() => {
+ jest.useRealTimers();
+ });
+
+ it('escapes a body variable in the html email while leaving it raw in the plain text email', async () => {
+ const { html, text } = await deliverToRecipient({
+ bodyTemplate: paragraphDocument('Hi {{firstName}}, welcome.'),
+ variables: { firstName: '<img src=x onerror=alert(1)>' },
+ });
+
+ expect(html).toContain('Hi &lt;img src=x onerror=alert(1)&gt;, welcome.');
+ expect(html).not.toContain('onerror=alert(1)>');
+ expect(text).toContain('Hi <img src=x onerror=alert(1)>, welcome.');
+ });
+
+ it('keeps a variable used inside a link href from breaking out of the attribute', async () => {
+ const { html } = await deliverToRecipient({
+ bodyTemplate: serializeDocument([
+ {
+ type: 'paragraph',
+ content: [
+ {
+ type: 'text',
+ text: 'Read more',
+ marks: [
+ {
+ type: 'link',
+ attrs: { href: 'https://example.com/u/{{token}}' },
+ },
+ ],
+ },
+ ],
+ },
+ ]),
+ variables: { token: '" onmouseover="alert(1)' },
+ });
+
+ expect(html).toContain(
+ 'href="https://example.com/u/%22%20onmouseover%3D%22alert(1)"',
+ );
+ expect(html).not.toContain('onmouseover="');
+ });
+
+ it('neutralises a javascript scheme carried by a variable bound as a whole href', async () => {
+ const { html } = await deliverToRecipient({
+ bodyTemplate: serializeDocument([
+ {
+ type: 'button',
+ attrs: { href: '{{website}}', style: {} },
+ content: [{ type: 'text', text: 'Open' }],
+ },
+ ]),
+ variables: { website: 'javascript:alert(1)' },
+ });
+
+ expect(html).toContain('Open');
+ expect(html).not.toContain('javascript:');
+ });
+
+ it('gives a variable used twice a single slot and the same value in both bodies', async () => {
+ const { variableNames, html, text } = await deliverToRecipient({
+ bodyTemplate: paragraphDocument(
+ '{{firstName}} {{lastName}}, this is for {{firstName}}.',
+ ),
+ variables: { firstName: 'Ada', lastName: 'Lovelace' },
+ });
+
+ expect(variableNames).toEqual(['firstName', 'lastName']);
+ expect(html).toContain('Ada Lovelace, this is for Ada.');
+ expect(text).toContain('Ada Lovelace, this is for Ada.');
+ });
+
+ it('personalises the subject of a campaign that has no body at all', async () => {
+ for (const bodyTemplate of ['', ' ']) {
+ const { subject, html, text } = await deliverToRecipient({
+ subjectTemplate: 'Hi {{firstName}}, a word',
+ bodyTemplate,
+ variables: { firstName: '<b>Ada</b>' },
+ });
+
+ expect(subject).toBe('Hi <b>Ada</b>, a word');
+ expect(html).toBe('');
+ expect(text).toBe('');
+ }
+ });
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts b/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts
new file mode 100644
index 00000000000..706750872d4
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/build-campaign-batch-replacements.util.ts
@@ -0,0 +1,23 @@
+import { escapeHtml } from 'src/engine/core-modules/emailing-domain/utils/escape-html.util';
+
+export const buildCampaignBatchReplacements = ({
+ variableNames,
+ variables,
+}: {
+ variableNames: string[];
+ variables: Record<string, string>;
+}): Record<string, string> => {
+ const replacements: Record<string, string> = {};
+
+ for (const [index, variableName] of variableNames.entries()) {
+ const value = Object.prototype.hasOwnProperty.call(variables, variableName)
+ ? (variables[variableName] ?? '')
+ : '';
+
+ replacements[`v_h_${index}`] = escapeHtml(value);
+ replacements[`v_t_${index}`] = value;
+ replacements[`v_u_${index}`] = encodeURIComponent(value);
+ }
+
+ return replacements;
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/build-campaign-delivery-settle-query.util.ts b/packages/twenty-server/src/modules/emailing/utils/build-campaign-delivery-settle-query.util.ts
new file mode 100644
index 00000000000..d6720748419
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/build-campaign-delivery-settle-query.util.ts
@@ -0,0 +1,43 @@
+import { type CampaignDeliverySettlement } from 'src/modules/emailing/types/campaign-delivery-settlement.type';
+
+export const buildCampaignDeliverySettleQuery = ({
+ workspaceId,
+ claimToken,
+ settlements,
+}: {
+ workspaceId: string;
+ claimToken: string;
+ settlements: CampaignDeliverySettlement[];
+}): { sql: string; parameters: unknown[] } => ({
+ sql: `
+WITH settled AS (
+ UPDATE "core"."campaignDelivery" delivery
+ SET
+ "state" = source."state",
+ "skipReason" = source."skipReason",
+ "failureReason" = source."failureReason",
+ "providerMessageId" = source."providerMessageId",
+ "sentAt" = source."sentAt",
+ "updatedAt" = now(),
+ "claimToken" = NULL,
+ "claimExpiresAt" = NULL
+ FROM unnest($1::uuid[], $2::text[], $3::text[], $4::text[], $5::text[], $6::timestamptz[])
+ AS source("id", "state", "skipReason", "failureReason", "providerMessageId", "sentAt")
+ WHERE delivery."id" = source."id"
+ AND delivery."workspaceId" = $7
+ AND delivery."claimToken" = $8
+ RETURNING delivery."id"
+)
+SELECT "id" FROM settled
+`,
+ parameters: [
+ settlements.map(({ deliveryId }) => deliveryId),
+ settlements.map(({ state }) => state),
+ settlements.map(({ skipReason }) => skipReason ?? null),
+ settlements.map(({ failureReason }) => failureReason ?? null),
+ settlements.map(({ providerMessageId }) => providerMessageId ?? null),
+ settlements.map(({ sentAt }) => sentAt ?? null),
+ workspaceId,
+ claimToken,
+ ],
+});
diff --git a/packages/twenty-server/src/modules/emailing/utils/chunk-recipients-to-admissible-size.util.ts b/packages/twenty-server/src/modules/emailing/utils/chunk-recipients-to-admissible-size.util.ts
new file mode 100644
index 00000000000..8941a02291a
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/chunk-recipients-to-admissible-size.util.ts
@@ -0,0 +1,22 @@
+import chunk from 'lodash.chunk';
+
+// The batch size is chosen from the instance-wide send limit, but the bucket
+// that admits it can be a lower per-workspace override. A batch costing more
+// than that limit is refused at any moment, so waiting longer never helps and
+// the recipients would eventually be failed as rate limited. Splitting to the
+// limit is what lets them go out.
+export const chunkRecipientsToAdmissibleSize = <TRecipient>({
+ recipients,
+ limitValue,
+}: {
+ recipients: TRecipient[];
+ limitValue: number | null;
+}): TRecipient[][] => {
+ const admissibleSize = Math.floor(limitValue ?? 0);
+
+ if (admissibleSize < 1 || recipients.length <= admissibleSize) {
+ return [recipients];
+ }
+
+ return chunk(recipients, admissibleSize);
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts b/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts
new file mode 100644
index 00000000000..4950279a936
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/compile-campaign-batch-template.util.ts
@@ -0,0 +1,110 @@
+import { msg } from '@lingui/core/macro';
+import {
+ type EmailDocumentStringContext,
+ isDefined,
+ parseCanonicalEmailDocument,
+ parseJson,
+} from 'twenty-shared/utils';
+
+import { compileOutboundEmailContent } from 'src/engine/core-modules/email/utils/compile-outbound-email-content.util';
+import { resolveEmailDocumentBindings } from 'src/engine/core-modules/email/utils/resolve-email-document-bindings.util';
+import {
+ EmailingDomainException,
+ EmailingDomainExceptionCode,
+} from 'src/engine/core-modules/emailing-domain/exceptions/emailing-domain.exception';
+import { type EmailingDomainEmailTemplate } from 'src/engine/core-modules/emailing-domain/drivers/types/emailing-domain-email-template.type';
+import { CAMPAIGN_VARIABLE_PATTERN } from 'src/modules/emailing/constants/campaign-variable-pattern.constant';
+
+const CAMPAIGN_BATCH_TAG_PREFIXES = {
+ htmlEscaped: 'v_h',
+ raw: 'v_t',
+ urlEncoded: 'v_u',
+} as const;
+
+type CampaignBatchTagFamily = keyof typeof CAMPAIGN_BATCH_TAG_PREFIXES;
+
+type CampaignBatchTagFamilyByContext = Record<
+ EmailDocumentStringContext,
+ CampaignBatchTagFamily
+>;
+
+const HTML_BODY_TAG_FAMILY_BY_CONTEXT: CampaignBatchTagFamilyByContext = {
+ html: 'htmlEscaped',
+ text: 'htmlEscaped',
+ url: 'urlEncoded',
+};
+
+const PLAIN_TEXT_BODY_TAG_FAMILY_BY_CONTEXT: CampaignBatchTagFamilyByContext = {
+ html: 'htmlEscaped',
+ text: 'raw',
+ url: 'urlEncoded',
+};
+
+export const compileCampaignBatchTemplate = async ({
+ subjectTemplate,
+ bodyTemplate,
+}: {
+ subjectTemplate: string;
+ bodyTemplate: string;
+}): Promise<{
+ template: EmailingDomainEmailTemplate;
+ variableNames: string[];
+}> => {
+ const variableNames: string[] = [];
+
+ const indexOfVariable = (variableName: string): number => {
+ const existingIndex = variableNames.indexOf(variableName);
+
+ if (existingIndex !== -1) {
+ return existingIndex;
+ }
+
+ return variableNames.push(variableName) - 1;
+ };
+
+ const toTags = (value: string, tagFamily: CampaignBatchTagFamily): string =>
+ value.replace(
+ CAMPAIGN_VARIABLE_PATTERN,
+ (_match, variableName) =>
+ `{{${CAMPAIGN_BATCH_TAG_PREFIXES[tagFamily]}_${indexOfVariable(variableName)}}}`,
+ );
+
+ const subject = toTags(subjectTemplate, 'raw');
+
+ if (bodyTemplate.trim() === '') {
+ return { template: { subject, text: '', html: '' }, variableNames };
+ }
+
+ const parseResult = parseCanonicalEmailDocument(
+ parseJson<unknown>(bodyTemplate),
+ );
+
+ if (!parseResult.success) {
+ throw new EmailingDomainException(
+ `Campaign bodyTemplate is not a renderable email document: ${parseResult.error}`,
+ EmailingDomainExceptionCode.MESSAGE_CAMPAIGN_NOT_SENDABLE,
+ { userFriendlyMessage: msg`This campaign's email content is invalid.` },
+ );
+ }
+
+ const emailDocument = parseResult.document;
+
+ const compileTaggedDocument = (
+ tagFamilyByContext: CampaignBatchTagFamilyByContext,
+ ) =>
+ compileOutboundEmailContent(
+ resolveEmailDocumentBindings(emailDocument, (value, context) =>
+ toTags(value, tagFamilyByContext[context]),
+ ),
+ );
+
+ const { html } = await compileTaggedDocument(HTML_BODY_TAG_FAMILY_BY_CONTEXT);
+ const { plainText } = await compileTaggedDocument(
+ PLAIN_TEXT_BODY_TAG_FAMILY_BY_CONTEXT,
+ );
+
+ return {
+ template: { subject, text: plainText, html: isDefined(html) ? html : '' },
+ variableNames,
+ };
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/compute-send-slot-backoff-ms.util.ts b/packages/twenty-server/src/modules/emailing/utils/compute-send-slot-backoff-ms.util.ts
new file mode 100644
index 00000000000..c03192efb75
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/compute-send-slot-backoff-ms.util.ts
@@ -0,0 +1,26 @@
+import { SEND_SLOT_RETRY } from 'src/engine/core-modules/emailing-domain/constants/send-slot-retry.constant';
+
+export const computeSendSlotBackoffMs = ({
+ attemptCount,
+ retryDelayMs,
+ windowMs,
+}: {
+ attemptCount: number;
+ retryDelayMs: number;
+ windowMs: number;
+}): number => {
+ const backoffCeilingMs = Math.min(
+ windowMs * SEND_SLOT_RETRY.maxWindows,
+ SEND_SLOT_RETRY.maxDelayMs,
+ );
+
+ const backoffMs = Math.min(
+ retryDelayMs * 2 ** (attemptCount - 1),
+ Math.max(backoffCeilingMs, SEND_SLOT_RETRY.minDelayMs),
+ );
+
+ const jitteredBackoffMs =
+ backoffMs * (1 + Math.random() * SEND_SLOT_RETRY.jitterRatio);
+
+ return Math.ceil(Math.min(jitteredBackoffMs, SEND_SLOT_RETRY.maxDelayMs));
+};
diff --git a/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-batch-settlements.util.ts b/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-batch-settlements.util.ts
new file mode 100644
index 00000000000..a14f49d24ee
--- /dev/null
+++ b/packages/twenty-server/src/modules/emailing/utils/resolve-campaign-batch-settlements.util.ts
@@ -0,0 +1,85 @@
+import { CAMPAIGN_DELIVERY_STATE } from 'src/engine/core-modules/emailing-domain/constants/campaign-delivery-state.constant';
+import { CAMPAIGN_FAILURE_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-failure-reason.constant';
+import { CAMPAIGN_SKIP_REASON } from 'src/engine/core-modules/emailing-domain/constants/campaign-skip-reason.constant';
+import { type CampaignBatchSendOutcome } from 'src/modules/emailing/types/campaign-batch-send-outcome.type';
+import { type CampaignDeliverySettlement } from 'src/modules/emailing/types/campaign-delivery-settlement.type';
+import { resolveCampaignSendFailure } from 'src/modules/emailing/utils/resolve-campaign-send-failure.util';
+import { isDefined } from 'twenty-shared/utils';
+
+export const resolveCampaignBatchSettlements = ({
+ claimedRecipients,
+ outcome,
+}: {
+ claimedRecipients: { messageId: string }[];
+ outcome: CampaignBatchSendOutcome;
+}): CampaignDeliverySettlement[] => {
+ const settlementByDeliveryId = new Map<string, CampaignDeliverySettlement>();
+
+ for (const recipientIndex of outcome.suppressedRecipientIndexes) {
+ const recipient = claimedRecipients[recipientIndex];
+
+ if (!isDefined(recipient)) {
+ continue;
+ }
+
+ settlementByDeliveryId.set(recipient.messageId, {
+ deliveryId: recipient.messageId,
+ state: CAMPAIGN_DELIVERY_STATE.SKIPPED,
+ skipReason: CAMPAIGN_SKIP_REASON.SUPPRESSED,
+ failureReason: null,
+ providerMessageId: null,
+ sentAt: null,
+ });
+ }
+
+ for (const entry of outcome.entries) {
+ const recipient = claimedRecipients[entry.recipientIndex];
+
+ if (!isDefined(recipient)) {
+ continue;
+ }
+
+ if (!isDefined(entry.messageId)) {
+ const { state, skipReason, failureReason } = resolveCampaignSendFailure(
+ new Error(entry.errorMessage ?? 'Provider rejected the destination'),
+ );
+
+ settlementByDeliveryId.set(recipient.messageId, {
+ deliveryId: recipient.messageId,
+ state,
+ skipReason,
+ failureReason,
+ providerMessageId: null,
+ sentAt: null,
+ });
+
+ continue;
+ }
+
+ settlementByDeliveryId.set(recipient.messageId, {
+ deliveryId: recipient.messageId,
+ state: CAMPAIGN_DELIVERY_STATE.SENT,
+ skipReason: null,
+ failureReason: null,
+ providerMessageId: entry.messageId,
+ sentAt: new Date(),
+ });
+ }
+
+ for (const recipient of claimedRecipients) {
+ if (settlementByDeliveryId.has(recipient.messageId)) {
+ continue;
+ }
+
+ settlementByDeliveryId.set(recipient.messageId, {
+ deliveryId: recipient.messageId,
+ state: CAMPAIGN_DELIVERY_STATE.FAILED,
+ skipReason: null,
+ failureReason: CAMPAIGN_FAILURE_REASON.UNKNOWN,
+ providerMessageId: null,
+ sentAt: null,
+ });
+ }
+
+ return [...settlementByDeliveryId.values()];
+};