Marketing Cloud
The Marketing Cloud connector reads rows from Salesforce Marketing Cloud Engagement Data Extensions and writes rows to them. It also reads contacts, the people Marketing Cloud knows across your Data Extensions.
When to use it
- You build a segment in a warehouse or a CRM and write it into a Data Extension that a journey or an email send reads from.
- You read a Data Extension into a warehouse, a file or a database for reporting.
- You run a data pipeline on a schedule to keep a Data Extension in step with a source system.
For Sales Cloud or Service Cloud records, use the Salesforce connector. A Marketing Cloud connection cannot reach Salesforce objects.
What you need
- An Installed Package in Marketing Cloud with a Server-to-Server API Integration component.
- The component's client ID and client secret.
- Your Marketing Cloud subdomain.
- Optional: the MID of the business unit to use.
Set up in Marketing Cloud
- In Marketing Cloud, go to Setup > Apps > Installed Packages and add a package.
- Add an API Integration component of type Server-to-Server.
- Grant it read and write access to Data Extensions.
- Copy the client ID and client secret. The secret is shown once.
Marketing Cloud uses the client credentials grant. There is no Connect button and no sign-in window.
Find your subdomain
The Installed Package shows three base URIs. They start with the same
28-character subdomain, such as mc563885gzs27c5t9-63k636ttgm:
https://mc563885gzs27c5t9-63k636ttgm.auth.marketingcloudapis.com/
https://mc563885gzs27c5t9-63k636ttgm.rest.marketingcloudapis.com/
https://mc563885gzs27c5t9-63k636ttgm.soap.marketingcloudapis.com/
Enter the subdomain only. DataLug builds the three addresses from it.
Connect
The connection form lists its steps on the left. Open any step from that list. The Environments step holds the values that differ per environment.
Test connection is in the form footer. Beside it, Test against picks Base, the connection as saved, or an environment, whose values are applied first.
| Field | Step | What to enter |
|---|---|---|
| Auth Type | Authentication | OAuth. Marketing Cloud offers a server-to-server integration only. |
| Client Id | Authentication | From Setup > Installed Packages, on the API Integration component. |
| Client Secret | Authentication | Shown once when the component is created. |
| Subdomain | Connection | The 28 characters starting mc, from your Auth Base URI. |
| Business Unit MID | Connection | Optional. Blank uses the package's own business unit. |
Stored secrets are never sent back to the browser. To change one, use Replace.
Business units
One Installed Package can act as any business unit it has access to. The MID selects which one. For several business units, create one connection per unit with the same client ID and secret and a different MID. Each connection reads only its own unit's data.
Supported operations
| Object | Source | Load |
|---|---|---|
| Data Extension Row | Query | Upsert |
| Contacts | Query | Not supported |
Not supported: Insert-only writes, Update, Delete, a source filter, starting journeys, sending email, starting automations, tracking and engagement events.
Read a Data Extension
- Add a Source node and select the Marketing Cloud connection.
- Open Configure Action. DataLug lists the Data Extensions in the connected
business unit as
Name (External Key). Search matches either. - Select one. DataLug reads its columns.
- Choose the columns to read.
DataLug follows the pages for you. A source filter stops the run with a message. Filter downstream with a Transform node.
Write to a Data Extension
- Add a Load node and select the Marketing Cloud connection.
- Choose the Data Extension.
- Map your input columns onto its columns.
- Choose a Write Mode.
Upsert is the only operation. It creates a row or updates it, matched on the Data Extension's primary key as set in Marketing Cloud. Map and populate the primary key columns in every row. A row with an empty primary key is reported as failed and is not sent.
| Write Mode | Requests | What dl_error tells you |
|---|---|---|
| Batch | One per chunk | Which chunk failed, not which row |
| Single record | One per row | Which row failed |
Batch is the default. Marketing Cloud answers once for a whole batch, so a failure marks every row in it. Switch to Single record to find the row.
Contacts
Contacts are read-only. There is one contact list per business unit, so there is no Data Extension to choose.
Limits
The API limits card has no default throttle for Marketing Cloud. Page size is at most 2,500.
The API limits card on the connection form is collapsed by default. Every field on it is optional, and a blank field uses the default shown below it.
| Setting | What it does | Default |
|---|---|---|
| Requests per period, Period | Paces outgoing calls. Set both to throttle. | No throttle, or the rate shown on the card. |
| Page size | Rows per request. A larger value is reduced to the provider's maximum. | The maximum shown on the card, or set by the provider. |
| Max attempts | Tries per call, including the first. | 3 |
| Cool-off (ms) | The first wait after a 429. Later waits grow from it. | 500 ms |
| Requests at once | Requests open at the same time within one run. | No limit |
A Retry-After header from the provider overrides the cool-off. The pace
applies per connection and is shared by every run on it. See
Run performance.
DataLug retries a call that the provider refused with 429, and a call that
could not connect. A read is also retried after a 408, a 5xx or a dropped
connection. A write is retried only after a 429 or a failed connection.
A Retry-After delay of up to one minute is honoured. A longer one fails the
call with the 429.
Troubleshooting
| What you see | What it means | What to try |
|---|---|---|
This Marketing Cloud connection has no valid subdomain. | Subdomain holds a full address or another value. | Enter the 28 characters only, with no https:// and no .auth.marketingcloudapis.com. |
Unauthorized or 401 on test | The client ID and secret do not match a live API Integration component. | Copy them from the right Installed Package. Check the component is Server-to-Server. |
| The test passes but no Data Extensions are listed | The integration cannot read Data Extensions. | Grant the component read access to Data Extensions, save the package, and test again. A permission change can take a few minutes. |
| A Data Extension you see in Email Studio is not listed | It belongs to a different business unit. | Set Business Unit MID to the unit that owns it. |
| Rows read with the right count and no values | The response shape was not recognised. | The account Owner emails DataLug support at support@datalug.io with the Data Extension name. |
| A write reports success but the rows are not there | The primary key columns are not mapped or are empty. | Map and populate every primary key column. |
Data Extension "<key>" has no primary key, so rows cannot be matched. | The Data Extension has no primary key. | Set one in Marketing Cloud, or write to a Data Extension that has one. |
| Every row in a load reports the same error | Write Mode is Batch. | Switch to Single record and run again to find the row. |
Marketing Cloud cannot filter a read. | The Source node has a filter. | Remove it and filter downstream with a Transform node. |
Related
- Source node, Load node and Transform node.
- Connections for environments and sharing.
- Salesforce.