Sfmc Engagement

SFMC Engagement Development

Generate production-grade Salesforce Marketing Cloud Engagement artifacts — AMPscript, Server-Side JavaScript, REST/SOAP API clients, Journey Builder configurations, Automation Studio workflows, and data extension models — with correct syntax, governor / throttle awareness, and an understanding of the SFMC security and business-unit model.

Before Writing Any Code

1. Identify the SFMC surface. Is this:

   • Content personalization inside an email or CloudPage (AMPscript or SSJS)?
   • An automation — Query Activity, Filter, Data Extract, Script Activity?
   • A journey — entry source, activities, decision splits, goals?
   • An external integration — REST / SOAP API from an outside system (Salesforce core, a web app, an ERP)?
   • A Marketing Cloud Connect sync with core Salesforce?

   The answer changes which reference doc matters most.

2. Identify the data model. SFMC separates Lists (legacy, flat) from Data Extensions (relational, modern). Contacts are keyed by Subscriber Key, not email — email is just an attribute. Sendable DEs require a SubscriberKey relationship. Get this wrong and sends fail silently or send to the wrong audience. Read reference/data-extensions/de-vs-list.md and reference/data-extensions/sendable-des.md.

3. Identify the business unit. Multi-BU orgs route sends, automations, and packages per BU. An installed package / API integration lives at Enterprise level but operates against specific BUs via mid= headers / businessUnit overrides. Cross-BU data visibility depends on Enterprise 2.0 configuration. Read reference/apis/business-units-and-packages.md.

4. Identify the auth flow. Modern SFMC uses OAuth 2.0 via Installed Packages. Two modes:

   • client_credentials — server-to-server, no user context, simplest.
   • jwt_bearer — user-context integrations, MFA-compatible, required for some scopes. Read reference/apis/oauth-flows.md.

AMPscript vs SSJS — choose deliberately

Default rule: use AMPscript for personalization inside email/CloudPage content. Use SSJS when you need JSON handling, external HTTP, or complex logic. Do not mix modes inside a single block unnecessarily — pick one per content area.

Read reference/ampscript/ampscript-language-overview.md and reference/ssjs/ssjs-core-library.md before choosing.

Journey Builder Rules

• Re-entry mode matters. "No re-entry" vs "Re-entry anytime" vs "Re-entry only after exiting" — choosing wrong traps or double-sends contacts.
• Wait By Attribute ≠ Wait By Duration. Wait By Attribute references a datetime on the contact record and waits until that moment; Wait By Duration is a fixed delta. Use the former for "send N days before birthday," never a calculated delta.
• Goals evaluate on exit, not continuously (unless configured otherwise). Understand "goal met = contact exits" semantics before depending on them.
• Transactional journeys (via Transactional Messaging API) are a separate system — real-time, no throttling via send classifications, different audit trail.

Read reference/journey-builder/journey-configuration.md, reference/journey-builder/re-entry-and-goals.md, and reference/journey-builder/transactional-messaging-api.md.

Data Extension Rules

• Sendable DE requires a primary key AND a SubscriberKey relationship mapping. Without it, the DE doesn't appear in the Send flow.
• Relational DEs work like database tables — join via LookupRows in AMPscript, Retrieve with filters in SSJS/SOAP. Plan your keys before you load data.
• Retention policies apply per-DE and delete data automatically. Defaults are aggressive; verify retention on every new DE or you'll silently lose history.
• Shared DEs (Enterprise 2.0) let child BUs read from parent DEs. Write permissions and override semantics matter.

Read reference/data-extensions/de-structure-and-keys.md and reference/data-extensions/retention-policies.md.

Automation Studio Rules

• Query Activities run SQL (ANSI-SQL-ish dialect) against DEs. Target must exist and have matching columns. No joins across BUs (unless shared DE).
• File Drop automations fire when a file lands in the Enhanced FTP. Filename masking with wildcards is your main trigger filter.
• Scheduled vs Triggered — schedule for time-based recurrence; trigger for event-driven. A single automation can have both (e.g., a scheduled nightly run with a manual trigger-on-demand option).
• Error notifications go to the "Run As" user by default — verify that's a real monitored mailbox, not someone who left.

Read reference/automation-studio/automation-activities.md and reference/automation-studio/scheduling-and-triggering.md (TODO).

API Rules

• Always use the installed-package OAuth flow. No username/password API auth in modern SFMC.
• The REST token endpoint is tenant-specific: https://<your-tenant-subdomain>.auth.marketingcloudapis.com/v2/token. Do not hardcode auth.exacttargetapis.com or similar — that was the legacy shared endpoint.
• REST is JSON and covers Assets, Journeys, Contacts, Transactional Messaging. SOAP covers Retrieves, Sends, Subscribers, DE rows — still required for many operations.
• Rate limits apply per package per minute. Back off on 429s with exponential delay.

Read reference/apis/rest-api-overview.md, reference/apis/soap-api-overview.md, and reference/apis/oauth-flows.md.

Marketing Cloud Connect

• MC Connect is a managed package installed in core Salesforce that connects to SFMC. Enables sending from Salesforce (via the Send Email button, triggered sends, journey entry), syncing reports, and exposing Contact/Lead data to SFMC.
• Sync data sources replicate Salesforce objects to Synchronized Data Extensions — different from regular DEs, read-only, auto-updating.
• The MC Connect user (in Salesforce) needs specific permissions: "Marketing Cloud User" checkbox on the User record, plus access to MC-related objects.
• Do not rely on MC Connect for high-volume real-time sync — it's batch-oriented. For real-time, use the REST API directly from Apex / Flow.

Read reference/mc-connect/mc-connect-overview.md and reference/mc-connect/sync-data-extensions.md (TODO).

Code Style

• AMPscript: block style with %%[ ... ]%%, one statement per line, meaningful variable names (@firstName, not @x). Always wrap Lookup / LookupRows in a null-check or IIF fallback.
• SSJS: wrap in Platform.Load("Core", "1.1.1") when using Core library. Use try/catch around HTTP calls. Never debug in production templates — remove before going live.
• Apex (for REST client): Named Credential for the token endpoint and the REST base URL. Token caching in a Cache.Org partition — MC tokens last ~20 minutes, don't re-auth on every callout. HttpCallout-based client with typed response wrappers.
• JavaScript (for Node client): use the official fuel-rest / fuel-soap SDKs or a thin axios wrapper. Implement token refresh-on-401.

Reference Docs

Read the relevant reference doc BEFORE generating code. Files marked (TODO) are scaffolded but not yet distilled — pull official docs via exa.ai and distill per scripts/distillation-template.md.

Templates

Use these as starting points when generating integrations:

Checklists

Offer relevant checklists when setting up or going live: