Salesforce Marketing Cloud (SFMC)#

Purpose: (Planned) Add inactive person emails to account-specific Auto Suppression Lists (data extensions) via REST. Production marketing suppression today uses the N04 CSV deliverable — see MARKETING_SUPPRESSION.html.

Code: src/auto_responder/services/sfmc/client.py, mock: mock.py

Configuration#

Setting	Notes
`SFMC_CLIENT_ID`, `SFMC_CLIENT_SECRET`	Server-to-server integration credentials.
`SFMC_AUTH_BASE_URI`	OAuth token endpoint base (e.g. `https://SUBDOMAIN.auth.marketingcloudapis.com`).
`SFMC_REST_BASE_URI`	REST base (optional; may be filled from token response).
`SFMC_SUPPRESSION_LIST_MAPPING`	JSON map: `AccountName` (from email repository) → Data Extension key for upsert.

Pipeline touch (not production)#

Live SFMC suppression is not hooked up in production. The call below exists in code but typically runs against MockSFMCClient or skips when mapping/credentials are missing. Marketing relies on N04 CSV imports instead.

When enabled, it would be invoked from ActionEngine._handle_inactive (inactive determination), after IPv4 + ACE status work:

Call	When
`add_to_suppression_list(account_name, email)`	`self.sfmc` is not None, client has the method, `account_name` non-empty, client `available`

account_name comes from email.inbox_source (typically AccountName from the central email row).
If there is no mapping for that account in sfmc_suppression_list_mapping, the client logs and skips the upsert.
Never called from _handle_active, _handle_title_update, or _handle_out_of_office. Suppression only fires on a confirmed INACTIVE determination.

End-of-run marketing deliverables (production)#

Notifier.notify_marketing_suppression (N04) emails SFMC-ready suppression import file(s) named {BusinessUnit}_NoLongerThere_{YYYY-MM-DD}.csv (glob *_NoLongerThere_*.csv in the run directory; currently always Marketing_...) to the shared marketing team mailbox (NOTIFICATION_EMAIL_ERIN → marketing-team-cbi@columbiabooks.com) after each run when inactive-people rows produced at least one deliverable. Columns: Email Address, Status (Unsubscribed), Date Added (run date). Global Max + Vish Cc applies. Internal output_document_inactive_people.csv is still written for ops traceability but is not attached. Changed-email rows remain on the master ledger; they are not bundled into this email.

Supporting:

Call	Purpose
`check_health()`	Used during live client init in `main.py` to confirm token obtain and choose real vs mock client

Planned REST suppression writes#

When live SFMC is configured, REST upsert to the mapped suppression data extension (live client) would run per inactive email. This is distinct from Salesforce CRM objects and from the N04 CSV import path. Until then, sfmc_suppression_added on internal inactive-people rows will usually remain No.

Writes (current state)#

No production SFMC writes today. Read-only and dry-run modes use the mock client; live runs without full SFMC config also avoid REST upserts. Marketing applies suppressions from N04 CSV attachments.

Operating modes#

Mode	Behavior
Live	Prefer `SFMCClient`; if credentials missing, `available` is false, or health check fails → `MockSFMCClient`
Read-only	Always `MockSFMCClient` in `main.py` (no REST writes)
Dry-run	`MockSFMCClient`

Output artifacts#

sfmc_suppression_added boolean on inactive-person output rows and processing reports.

MARKETING_SUPPRESSION.html — end-to-end suppression process and file changes (N04 + REST)
email-repository.html — source of AccountName / inbox source
salesforce.html — CRM is a different integration