Dotdigital: Telltide Seed Address Guide

Dotdigital separates its automation system (Programs) from its broadcast system (Campaigns). The most important constraint for seed management: bulk CSV imports do NOT fire join actions (welcome / program entry triggers). Only individual contact additions, via the UI, the single-contact API endpoint, or signup form submissions, fire join actions. Plan your seed injection method accordingly.

Quick reference

---

1. Scheduled / one-off sends (Campaigns)

Dotdigital Campaigns are one-time email sends. The audience is defined by selecting Address Books, Segments, and Marketing Preferences in the Campaign's Contacts step. Seeds must be in at least one selected Address Book.

Where to add seed addresses

Add the seed contact to any Address Book selected in the Campaign's Contacts step. The simplest approach: maintain a "Telltide Seeds" Address Book and include it in every Campaign.

Non-technical path

For CRM managers and marketing operators who do not write code.

Option A: Add an individual contact via the UI

1. Navigate to Contacts in the main nav.
2. Find or select your target Address Book (or navigate to the "Telltide Seeds" Address Book).
3. Click the Add contacts icon (person with + icon) next to the Address Book.
4. Select Add an individual contact.
5. Enter the seed email address.
6. Click Continue. The contact is created and the Manage contact page opens.
7. Fill in additional data fields (First Name, Last Name, any custom data fields needed for personalisation).
8. Save.

Option B: Upload a CSV

1. Navigate to Contacts > Upload contacts.
2. Choose the target Address Book (or "Telltide Seeds").
3. Upload a CSV with at least an Email column. Other columns map to custom data fields by name.
4. Confirm and run the import.

Caveat: CSV imports do NOT fire join actions. Use Option A or a signup form when the seed must enter a Program.

Option C: Subscribe via a Dotdigital signup form

If the Program is triggered by a signup-form join action, submit the seed email through the form just as a real subscriber would. This is the closest match to the live customer journey and fires the same join action.

Technical path

For email developers and ops engineers who will script seed placement.

API user setup

1. Expand the User menu (bottom left) and go to Settings > Access > API users.
2. Click NEW USER. The username is auto-generated in the format apiuser-XXXXXXXXX@apiconnector.com and cannot be edited.
3. Set a password (minimum 8 characters with at least one digit or non-alphanumeric).
4. Add a description (e.g. "Telltide seed automation") to identify the credential later.
5. Note the API endpoint shown at the top of the API users page. This is your account's regional host (for example r1-api, r2-api, r3-api). All requests must use this regional host.

Authentication is HTTP Basic Auth using the apiuser-... username and password.

Add a seed contact via API (single contact, fires join actions)

POST https://{region}-api.dotdigital.com/v2/address-books/{address_book_id}/contacts
Authorization: Basic {{base64(apiuser-XXXX@apiconnector.com:password)}}
Content-Type: application/json

{
  "email": "seed@example.com",
  "optInType": "Single",
  "emailType": "Html",
  "dataFields": [
    { "key": "FIRSTNAME", "value": "Seed" },
    { "key": "LASTNAME", "value": "Monitor" },
    { "key": "BIRTHDAY", "value": "1985-04-15" }
  ]
}

optInType values: Single (immediately subscribed), Double (sends a confirmation email first), Unknown.

This endpoint fires join actions. If the Address Book has a join action configured (for example "Enrol in welcome program"), it fires for this individual addition.

Bulk import contacts to an Address Book via API (does NOT fire join actions)

The bulk import endpoint takes multipart/form-data with a CSV or Excel file (10 MB cap). The file must include an Email column; other columns map to custom data fields by name.

POST https://{region}-api.dotdigital.com/v2/address-books/{address_book_id}/contacts/import
Authorization: Basic {{base64(apiuser-XXXX@apiconnector.com:password)}}
Content-Type: multipart/form-data; boundary=----boundary

------boundary
Content-Disposition: form-data; name="file"; filename="contacts.csv"
Content-Type: text/csv

Email,FIRSTNAME,LASTNAME
seed@example.com,Seed,Monitor
------boundary--

The response returns an import ID. Poll GET /v2/contacts/import/{id} for status. Bulk import does NOT fire join actions, so use the single-contact endpoint above when you need Programs to trigger.

Always-on flow coverage

Recurring Dotdigital Campaigns and any Program that runs on a schedule both depend on the seed continuing to satisfy the audience definition. Confirm:

• Address Book membership. The seed must remain in every Address Book selected in the Campaign Contacts step. If an operator swaps Address Books between sends, update the seed placement to match.
• Segment membership. If the Campaign also targets Segments, set the seed's data fields and engagement so it qualifies. The simplest approach is to target only the "Telltide Seeds" Address Book without segment restrictions.
• Marketing Preferences. If the Campaign filters by a Marketing Preference (an opt-in category), opt the seed in to that preference.
• Dynamic Content. Dotdigital supports dynamic content blocks within a Campaign, where different content variations show based on contact data field rules. Review every dynamic content rule so the seed receives the variation you intend to monitor (or set up multiple seeds, one per variation).
• Suppression status. If the seed becomes suppressed mid-cycle (hard bounce, complaint, manual suppression), all future sends are silently dropped. Monitor the seed's status field continuously.

Profile attributes required

Seeds need:

• Email address.
• Not on the account-level suppression list.
• Any custom data field values referenced in the email template's personalisation tags.

Gotchas

Suppression list: Dotdigital maintains an account-level suppression list (hard bounces, spam complaints, unsubscribes, manual suppressions). If the seed's email is suppressed, attempting to add them to an Address Book via API returns an error. Check suppression status before adding:

GET https://{region}-api.dotdigital.com/v2/contacts/{email}

Look at the status field in the response. If it shows a suppression reason, remove the suppression first:

DELETE https://{region}-api.dotdigital.com/v2/suppressions

Contact status types: Subscribed, Unsubscribed, SoftBounced, HardBounced, IspComplained, MailBlocked, DirectComplaint, Deleted, Suppressed, DomainSuppression, NoMxRecord.

---

2. Ongoing / automated journeys (Programs)

Dotdigital Programs are automated workflow sequences built in the Program Builder. Entry is configured in the Start node, which defines scheduling, enrolment rules, and enrolment limits.

Program entry trigger types

---

Creating trap profiles per journey type

Welcome / onboarding (Join action trigger)

• Trigger: Join action on Address Book. Fires when a contact is individually added to the Address Book that has the join action configured.
• Critical constraint: Bulk CSV import does NOT fire join actions. The contact must be added via:
• UI: Individual contact addition (Section 1, Non-technical path Option A).
• API: POST /v2/address-books/{id}/contacts (single contact endpoint).
• Signup form submission.
• Seed requirements: Email address, not on suppression list.
• How to trigger: 1. Navigate to the Address Book with the join action configured. 2. Add the seed contact individually via UI, signup form, or single-contact API. 3. The join action fires automatically and enrols the seed in the welcome Program.

Abandoned cart

• No native trigger: Dotdigital Programs do not have a built-in abandoned cart trigger.
• Workaround: Use the Program enrolment API to enrol the seed at the right moment.

POST https://{region}-api.dotdigital.com/v2/programs/enrolments
Authorization: Basic {{base64(apiuser-XXXX@apiconnector.com:password)}}
Content-Type: application/json

{
  "programId": {{program_id}},
  "contacts": [ {{contact_id}} ],
  "addressBooks": []
}

Note: the request body uses integer contact IDs in contacts and integer address book IDs in addressBooks. Resolve the email to a contact ID first via GET /v2/contacts/{email}.

• Data for personalisation: If the abandoned cart Program references order data (product names, cart value), those values must be set on the seed contact's data fields before the enrolment API is called.
• Set personalisation data on the seed contact first:

PUT https://{region}-api.dotdigital.com/v2/contacts/{contact_id}/data-fields
[
  { "key": "CARTVALUE", "value": "95.00" },
  { "key": "CARTPRODUCT1", "value": "Widget Pro" },
  { "key": "CARTURL", "value": "https://yourstore.com/cart" }
]

Then call the enrolment endpoint above.

Browse abandonment

• No native trigger: Same as abandoned cart.
• Workaround: Use the Program enrolment API after pre-setting the relevant product data fields on the seed.

Winback / re-engagement (Date-based enrolment)

• Trigger: Date field enrolment. The Program evaluates contacts whose LASTPURCHASEDATE field matches a relative date condition.
• Seed requirements: Email address, LASTPURCHASEDATE data field set to a date in the trigger window.
• Step 1: Create the custom data field (if it doesn't exist): 1. Navigate to Contacts > Data Fields > Create new data field. 2. Name: LASTPURCHASEDATE (no spaces allowed in field names). 3. Type: Date (ISO 8601 format YYYY-MM-DD). 4. Save.
• Step 2: Set the field on the seed contact:

PUT https://{region}-api.dotdigital.com/v2/contacts/{contact_id}/data-fields
[
  { "key": "LASTPURCHASEDATE", "value": "2025-12-01" }
]

• Program trigger configuration: In the Program's Start node, select "Date field based" enrolment rule, select LASTPURCHASEDATE, configure the relative date condition (for example "30 days after Last Purchase Date").
• For seed testing: Set the seed's LASTPURCHASEDATE to exactly 30 days ago (or whatever the trigger window requires). At the next scheduled enrolment check, the seed qualifies and enters the Program.

Post-purchase

• No native trigger: Requires an external system (ecommerce integration, CRM, or custom API) to call the Program enrolment API at order time.
• Workaround: Set order data fields on the seed contact, then call POST /v2/programs/enrolments.

PUT https://{region}-api.dotdigital.com/v2/contacts/{contact_id}/data-fields
[
  { "key": "ORDERID", "value": "TEST-ORD-001" },
  { "key": "ORDERTOTAL", "value": "149.99" },
  { "key": "ORDERPRODUCT", "value": "Widget Pro" }
]

Birthday / anniversary (Date-based enrolment, annually recurring)

• Trigger: Date field enrolment on BIRTHDAY data field, set to "Anniversary" frequency. Fires each year on the stored month and day.
• Seed requirements: Email address, BIRTHDAY data field (Date type) set on the contact.
• Date format: ISO 8601 YYYY-MM-DD.

Step 1: Create the BIRTHDAY data field (if it doesn't exist):

1. Contacts > Data Fields > Create new data field.
2. Name: BIRTHDAY (no spaces).
3. Type: Date.
4. Save.

Step 2: Set the birthday on the seed contact.

Via UI:

1. Navigate to the seed contact's record.
2. Find the BIRTHDAY data field.
3. Enter the date value (for example 1985-04-15).
4. Save.

Via API:

PUT https://{region}-api.dotdigital.com/v2/contacts/{contact_id}/data-fields
[
  { "key": "BIRTHDAY", "value": "1985-04-15" }
]

Step 3: Configure the Program's Start node:

• Enrolment rule: "Date field based".
• Select: BIRTHDAY.
• Frequency: "Anniversary" (fires annually on the stored month and day).

For same-day testing: Set the seed's BIRTHDAY to today's date. At the next scheduled enrolment evaluation (typically daily), the seed qualifies and enters the Program.

---

Always-on flow coverage

Many customer Programs run indefinitely against an Address Book, a Segment, or a recurring date field. To stay covered as a seed:

• Address Book membership. If the Program's Start node enrols from one or more Address Books, the seed must be in at least one. For Programs gated by a join action, every fresh enrolment requires a fresh individual addition (or a fresh signup form submission, or a fresh enrolment API call).
• Segment membership. If the Start node uses a Segment, set the seed's data fields, contact scoring, and Insight data so the Segment evaluates true at the scheduled enrolment check.
• Custom Data Fields. Date-based Programs read from a contact-level Date data field (BIRTHDAY, LASTPURCHASEDATE, etc.). Keep these populated on the seed in ISO 8601 format. For "Anniversary" frequency, only month and day matter, so set once and the Program re-fires yearly. For relative date rules ("30 days after"), roll the field forward each cycle.
• Anniversary frequency. Anniversary date fields are the cleanest always-on hook. Set the seed's date field once, and it qualifies again on every recurrence without further action.
• Enrolment limits. The Start node can cap enrolments per day, week, or in total. Verify the limit is not blocking the seed.
• Suppression. A suppressed seed is silently dropped from every Program send. Monitor status continuously.

Program enrolment via API (direct injection)

For Programs where join actions or date conditions are impractical to simulate, enrol the seed directly:

POST https://{region}-api.dotdigital.com/v2/programs/enrolments
Authorization: Basic {{base64(apiuser-XXXX@apiconnector.com:password)}}
Content-Type: application/json

{
  "programId": {{program_id}},
  "contacts": [ {{contact_id}} ],
  "addressBooks": []
}

contacts and addressBooks are integer ID arrays. Each call can enrol up to 25 contacts and / or whole Address Books. The operation is asynchronous; the response returns an enrolment ID.

Get the program ID: Navigate to Automation > Programs, click the target Program. The ID is visible in the page URL.

Check enrolment status:

GET https://{region}-api.dotdigital.com/v2/programs/enrolments/{enrolment_id}

---

Ensuring seeds progress through the full Program

Suppression check: If the seed becomes suppressed mid-Program (for example a hard bounce), subsequent emails will not deliver. Monitor the seed's status field throughout the Program duration.

Decision nodes: Programs use two-way and multi-decision nodes to branch contacts based on data field values or engagement. Review every decision node to ensure the seed follows the expected path.

Delay nodes: Programs can have significant wait times between steps. Plan seed monitoring around expected send timing.

Enrolment limits in Start node: The Start node can cap how many contacts enter per day, week, or total. Verify the limit is not blocking the seed.

---

How to reset seeds for repeated Program testing

Re-enrol via API: Call POST /v2/programs/enrolments again for the seed contact. Dotdigital allows re-enrolment unless the Start node enrolment limit prevents it.

Resubscribe via API: If the seed unsubscribed from an Address Book:

POST https://{region}-api.dotdigital.com/v2/address-books/{id}/contacts/resubscribe
{
  "unsubscribedContact": {
    "email": "seed@example.com"
  },
  "preferredLocale": "En_GB",
  "returnUrlToUseIfChallenged": "https://yoursite.com"
}

This re-adds the contact, with or without a re-confirmation email depending on the endpoint variant.

Remove from suppression list: If the seed is suppressed, remove the suppression before re-adding to Address Books:

DELETE https://{region}-api.dotdigital.com/v2/suppressions
Authorization: Basic {{...}}
Content-Type: application/json

{
  "email": "seed@example.com"
}

---

3. Platform-specific considerations

API options

Create a contact:

POST https://{region}-api.dotdigital.com/v2/contacts

Get contact by email:

GET https://{region}-api.dotdigital.com/v2/contacts/{email}

Update contact data fields:

PUT https://{region}-api.dotdigital.com/v2/contacts/{id}/data-fields

Add contact to Address Book (fires join actions):

POST https://{region}-api.dotdigital.com/v2/address-books/{id}/contacts

Bulk import to Address Book (does NOT fire join actions, multipart/form-data):

POST https://{region}-api.dotdigital.com/v2/address-books/{id}/contacts/import

Enrol contact in Program:

POST https://{region}-api.dotdigital.com/v2/programs/enrolments

Create contact data field:

POST https://{region}-api.dotdigital.com/v2/data-fields

Check / remove suppressions:

GET / DELETE https://{region}-api.dotdigital.com/v2/suppressions

API authentication: HTTP Basic Auth using the auto-generated apiuser-...@apiconnector.com username and the password set when the API user was created. Create API users in Settings > Access > API users.

Region-specific base URLs: Dotdigital uses regional hosts in the format https://r{N}-api.dotdigital.com/v2/ (for example r1-api, r2-api, r3-api). Find your account's host at the top of the Settings > Access > API users page. If unsure, call GET /v2/account-info against r1-api.dotdigital.com from any region. The response returns the correct regional endpoint for your account. Requests sent to the wrong regional host fail.

Rate limits

Dotdigital exposes two rate-limit schemes:

• Tiered (preferred): Per-minute limits split across tiers (Low, Medium, High, Unlimited). Endpoints are mapped to a tier, and headers indicate remaining quota. This is the current scheme.
• Flat (deprecated): Per-hour blanket limits.

Exact limits depend on package level (Basic, Standard, Enhanced) and tier assignment. Find your account's limits in Settings > Access > API rate limits. HTTP 429 is returned when limits are exceeded. Use bulk import endpoints for large operations to conserve quota, but remember bulk import does not fire join actions.

Duplicate contact handling

Unique identifier: Email address. If you POST /v2/contacts or POST /v2/address-books/{id}/contacts with an existing email, the existing record is updated, not duplicated.

CRM sync duplicates: If a contact's email address changes in a connected CRM, Dotdigital does not recognise the updated email as the same person and creates a new record. A CustomID field does not prevent this. Update the email in Dotdigital before the CRM sync runs to avoid duplicates.

Import conflicts: Conflicts occur if the email exists on the suppression list, in pending or unconfirmed contacts, or in the Recycle Bin. The import report flags these for manual resolution.

Platform-specific terminology

Plan tier gating

Dotdigital sells three packages: Basic, Standard, and Enhanced. Higher packages unlock larger API rate-limit tiers, more concurrent Programs, and access to advanced segmentation, contact scoring, and Insight data. Confirm with the customer's Customer Success Manager which package they are on if seed automation hits unexpected limits.

Known limitations and workarounds

Bulk CSV import does not fire join actions. This is the most impactful constraint for seed monitoring in Dotdigital. Always use the single-contact API endpoint, the UI individual-add flow, or a signup form when Program enrolment must trigger. Use bulk import only when populating Address Books for Campaign targeting without needing automation triggers.

No native behavioural triggers (abandoned cart, browse abandonment). These require external systems to call the Program enrolment API at the right moment. Set personalisation data fields on the seed before enrolment.

Data field names cannot contain spaces. When creating data fields for seed testing (for example LASTPURCHASEDATE, BIRTHDAY), use uppercase letters and no spaces. Dotdigital rejects field names with spaces.

Program enrolment API rate limit is low. Implementations should respect the per-hour cap and batch up to 25 contacts per call. Queue and back off on HTTP 429.

Date fields must be ISO 8601 format (YYYY-MM-DD). Do not use MM/DD/YYYY or DD/MM/YYYY in API calls or data field values.

Suppression status blocks all emails. A suppressed seed cannot receive any email from the account regardless of Address Book membership or Program enrolment. Verify suppression status before starting a new monitoring cycle. Remove suppression via the API before re-adding to Address Books.

Wrong regional host returns errors. Always resolve the account's regional host first. There is no automatic redirect between regions.