> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-server.md).

# Dotdigital server

This destination sends your Chord events and contact updates to Dotdigital from Chord's servers, over Dotdigital's v3 API. Because it runs server-side, it is unaffected by ad blockers and browser tracking restrictions. It is also the only version that can write a full contact record, including data fields and address book membership. See [Dotdigital](/activate/event-streaming/destinations/email-and-marketing/dotdigital.md) for how it fits with the [Dotdigital Tag](/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-tag.md) version.

## Getting started

You need:

* **An API user name and password.** Create a dedicated API user in Dotdigital under **Account > Settings > Access > API users**. Dotdigital generates the username, and you set the password. Create one API user for Chord rather than sharing an existing one, so it can be revoked on its own without breaking your other integrations. Dotdigital does not show the password again after you save it.
* **Your region**: `r1`, `r2` or `r3`. Your Dotdigital account lives in exactly one region, and it is part of every API hostname. Read it off the API endpoint shown on the same API users page.

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **API User Name** (required): the auto-generated username of a Dotdigital API user.
* **API User Password** (required): the password you set on that API user.
* **Region** (required): the Dotdigital region your account is hosted in: `r1`, `r2` or `r3`. Defaults to `r1`.
* **Contact Identifier** (required): which identifier Dotdigital keys contacts on, **Email** or **Mobile Number**. Defaults to **Email**. Pick mobile number only if your Dotdigital contacts are keyed on SMS. Mobile numbers must be in E.164 format (`+14155550123`), or Chord skips them. If an event has no value for the identifier you pick, Chord uses the other one.
* **Address Book ID** (optional): the address book new contacts are added to. Find the ID in the URL when you open the list under **Audience > Lists**. Adding a contact to an address book makes them mailable, so set this only where your consent flow allows it. See [Consent](#consent).
* **Create Contacts Automatically** (optional): Dotdigital only accepts events for contacts that already exist, so Chord creates or updates the contact before sending each event. On by default. Turn it off only if another system provisions your Dotdigital contacts. With it off, events for contacts Dotdigital does not know are rejected.
* **Cart URL** (required): your storefront's cart page URL. Dotdigital rejects a cart update unless every line has a product URL, and Chord falls back to this for a line that has none. Use the same value as the Dotdigital Tag version so an order looks the same whichever version reported it.
* **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md).

## Connect

Add **Dotdigital** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps.

## Event mapping

| Chord event                                               | Dotdigital event                                       | Notes |
| --------------------------------------------------------- | ------------------------------------------------------ | ----- |
| `identify`, `Email Captured`, `Signed Up`, `User Created` | Contact created or updated                             |       |
| `Product Viewed`, `Product List Viewed`                   | Event imported, with product data                      |       |
| `Product Added`, `Product Removed`, `Cart Viewed`         | Event imported, with cart data                         |       |
| `Checkout Started`                                        | Event imported, with cart data                         |       |
| `Order Completed`                                         | Event imported, with the order reference and cart data |       |
| Any other `track` event                                   | Event imported under its own name                      |       |
| `page`, `screen`                                          | Not sent. See Gotchas                                  |       |

Each imported event becomes a record in an Insight data collection named after the event. Dotdigital replaces non-alphanumeric characters with underscores when it names the collection, so `Order Completed` becomes `Order_Completed`.

## Contacts

An `identify` — and the identity-bearing track events above — create or update the Dotdigital contact.

| Chord source (priority order) | Dotdigital field           | Notes |
| ----------------------------- | -------------------------- | ----- |
| `email`                       | `identifiers.email`        |       |
| `phone`                       | `identifiers.mobileNumber` |       |
| `first_name`                  | `dataFields.firstName`     |       |
| `last_name`                   | `dataFields.lastName`      |       |
| **Address Book ID** setting   | `lists`                    |       |

Both identifiers are sent when both are known, regardless of which one addresses the contact — that is how a contact who arrived by email gains an SMS channel, and the other way round.

Identifiers go to Dotdigital **in plaintext**, and this is deliberate. Dotdigital has to actually deliver mail and SMS to the person, so it accepts no hashed identifier — hashing would break delivery rather than protect anything. If your security review needs to know exactly what Chord sends, that is the list above.

**Mobile numbers must be in E.164 format** — `+14155550123`. A number with no country code is skipped rather than guessed at: completing it would mean assuming a country, and a wrong assumption can resolve to a real contact somewhere else. Formatting like spaces, dashes and brackets is fine; a leading `00` is treated the same as `+`.

**Only `firstName` and `lastName` are sent as data fields.** Dotdigital data fields have to already exist in your account — you declare them in Dotdigital, and writing one Dotdigital does not know about does not create it. Rather than guess at your field names, Chord sends only these two and leaves the rest to you: map any other trait onto the exact data field name your account uses, using Property Mappings below.

## Consent

**Chord never sets a subscription status and never writes a consent record.** Both would manufacture consent out of the fact that somebody browsed a storefront. A contact Chord creates gets whatever status your Dotdigital account applies by default, and your own consent flow governs whether they become mailable.

The **Address Book ID** setting is the one exception, and it is opt-in for exactly this reason: adding a contact to an address book makes them mailable in Dotdigital. Set it only where your consent flow allows it. Leave it empty to create contacts with no list membership.

## Product and cart data

Commerce events carry the same product and cart shapes the [Dotdigital Tag](/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-tag.md) sends, so an order looks the same in Dotdigital whichever surface reported it. See that page's Product and cart data section for the full field tables.

That includes its **Fields Dotdigital requires** table. Those requirements are Dotdigital's, not the browser's, so they apply here too — for a cart event that is missing the subtotal or a line's product URL, Chord doesn't send the cart. It logs a warning, and Chord still imports the event without cart data. If Dotdigital rejects any other event with a `422`, Chord doesn't retry it, unlike a rate limit.

If Chord can't build a cart at all, because there is no cart ID or no product lines, it still imports the event with its other properties but without cart data.

Everything else your event carried is preserved alongside the commerce shape, so you can segment on your own properties. The raw `products` array is replaced by the Dotdigital-shaped one rather than sent twice.

## Property mappings

You can map any event property onto a destination field from the connection's mapping configuration. Mapped properties use a **bare path** — `properties.customer_type → customer_type`.

Two ways this is useful here:

* **Filling a Dotdigital data field.** Map a trait onto the exact data field name your Dotdigital account declares, so a contact update writes it.
* **Reshaping event data.** Mappings are applied before the payload is built, so a mapping that rewrites `properties.sku` changes what Chord reads for the product's SKU.

Everything an event carries beyond the commerce shape is imported as event data already, so a custom property does not need a mapping to reach Dotdigital's Insight data collection — mappings are for renaming and restructuring.

## Gotchas

**Every event needs a contact that already exists in Dotdigital.** This is Dotdigital's rule, not Chord's: the Events API rejects an event whose contact it does not know. That is why **Create Contacts Automatically** is on by default — Chord creates or updates the contact immediately before importing each event. Turn it off only if another system provisions your Dotdigital contacts, and be aware that with it off, events for contacts Dotdigital does not know are rejected.

It also means two requests per identified event rather than one, which counts against your Dotdigital rate limit. Your limit depends on your package and is shown under **Account > Settings > Access > API rate limits**.

**Anonymous events are not sent.** An event with no email address and no valid E.164 mobile number is skipped, because Dotdigital has no anonymous contact to attach it to. This is normal for storefront browsing traffic before a shopper identifies themselves — the [Dotdigital Tag](/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-tag.md) is the surface that captures pre-identification behaviour.

**Page views are not sent.** Dotdigital's own web behaviour tracking owns page views and writes them into a first-party collection that its Events API is not permitted to write into. A server-side page view could only land in a parallel collection duplicating data Dotdigital already holds in the place its features read from. Connect the [Dotdigital Tag](/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-tag.md) for page views.

**Custom events need the CXDP package** on your Dotdigital account, as does the event import generally. Without it Dotdigital cannot accept imported events.

**Nine collection names are reserved** by Dotdigital for its own features: `cartInsight`, `catalog`, `consentInsight`, `easyEditorExtensions`, `nostoEmailCampaigns`, `orders`, `productCategories`, `webInsight` and `wishList`. An event whose name matches one is skipped and logged.

**A successful response means accepted, not stored.** Dotdigital's event import is asynchronous and answers `202 Accepted`. Per-event validation problems surface in Dotdigital's own import status rather than in the response Chord sees, so a clean log entry in Chord is weaker evidence here than it would be for a synchronous API. Check the Insight data collection in Dotdigital when verifying a new connection.

**Data subject erasure is supported, with a 30-day delay.** Chord can action a deletion request against Dotdigital, which deletes the contact. Dotdigital then holds it in your account's recycle bin for **30 days** before removing it permanently, and an account administrator can recover it within that window. Chord has no way to empty the recycle bin, so if your statutory deadline is shorter than Dotdigital's 30 days, empty it yourself in Dotdigital under the recycle bin. Contacts who were already suppressed are the exception — their data fields and Insight data are removed immediately and cannot be recovered.

Erasure is addressed by email address only. Dotdigital's own contact ID is a key it assigns rather than one Chord knows, so a deletion request that names only a user ID is skipped rather than resolved against it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/activate/event-streaming/destinations/email-and-marketing/dotdigital/dotdigital-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.