SAP Emarsys: Telltide Seed Address Guide

SAP Emarsys uses a field-ID-based contact model where standard system fields are referenced by numeric IDs (e.g., field 3 = email, 31 = email opt-in). Automation is split between two builders: Automation Center for lifecycle management programs, and Interactions for real-time event-driven triggers. The most important constraint for seed management: test emails for event-triggered programs cannot be sent to manually entered addresses. They must be sent to contacts that already exist in the database so personalization tokens can resolve.

Quick reference

---

1. Scheduled / one-off sends (Email Campaigns)

Emarsys Email Campaigns are one-time or recurring batch sends. The audience is defined in the Recipient Source step: a Contact List, a Segment, or an API call. Seeds must be in the targeted contact list or segment at send time.

Where to add seed addresses

Add the seed contact to any Contact List targeted in the campaign's Recipient Source. Maintain a "Telltide Seeds" Contact List and include it as an additional Recipient Source in every campaign.

Limitation on test sends: Test emails (Copies) can only be sent to a Contact List, not to a Segment. The test contact list can contain a maximum of 50 contacts. Exceeding 50 results in an error and the test email is not sent.

Personalization requirement: Test emails cannot be sent to arbitrary email addresses if the email uses personalization tokens. The contact must exist in the database so Emarsys can resolve the personalization from their contact record.

Non-technical path

For CRM managers who do not write code. All seed placement happens inside the SAP Emarsys web UI.

Option A: Add via the Contacts UI (recommended for one or two seeds).

1. Navigate to Contacts in the main nav.
2. Select or create a Contact List (e.g., "Telltide Seeds").
3. Click Add Contact (the inline form).
4. Enter the seed email address into field 3 (Email).
5. Set field 31 (Email opt-in) to 1 (opted in).
6. Populate field 1 (First name) and field 2 (Last name) with values that satisfy any personalization tokens used in production templates.
7. Save the record.
8. Open every active Email Campaign and add the "Telltide Seeds" Contact List as an additional Recipient Source.

Option B: CSV import (recommended for batch seed loads).

1. Build a CSV with one row per seed and columns mapped to field IDs 3, 1, 2, 31.
2. Navigate to Contacts > Import.
3. Upload the CSV; choose field 3 (Email) as the unique identifier for deduplication.
4. Map the opt-in column to field 31 and confirm value 1 for every row.
5. Assign the import target to the "Telltide Seeds" Contact List.
6. Run the import and verify the resulting contact count.

Option C: Web form submit. If your account already exposes a public Emarsys-hosted web form, the seed can subscribe via that form. Useful for journeys that use a form-submit entry trigger because the same trigger that fires for real subscribers also fires for the seed.

Technical path

For email-dev or marketing-ops engineers integrating seed creation into a deployment pipeline. All examples target the v2 base URL https://api.emarsys.net/api/v2/. v3 endpoints are available under https://api.emarsys.net/api/v3/ for OAuth 2.0 / OIDC clients.

Authentication. v2 uses the Escher HTTP request signing scheme (X-EMS-Auth header plus X-EMS-Date). The legacy WSSE scheme (X-WSSE header with UsernameToken) is still accepted but deprecated, with sunset scheduled for end of 2026. New integrations should target v3 OAuth 2.0 with OIDC and JWT bearer tokens. Generate API credentials under Account Management > API settings (v2) or Admin > Integration > API credentials (v3).

Create or upsert a seed contact:

POST https://api.emarsys.net/api/v2/contact
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "contacts": [
    {
      "3": "seed@example.com",
      "1": "Seed",
      "2": "Monitor",
      "31": 1
    }
  ]
}

Field ID reference:

• 1 = First name
• 2 = Last name
• 3 = Email address
• 4 = Date of birth (format: YYYY-MM-DD)
• 31 = Email opt-in (1 = opted in, 2 = opted out, empty = unset)

key_id: Specifies which field is used as the lookup key for deduplication. "3" means email address.

Upsert behavior: Use PUT /api/v2/contact with the same body to upsert. If a contact matching key_id already exists, the existing record is updated; otherwise a new contact is created.

Add seed to a Contact List:

POST https://api.emarsys.net/api/v2/contactlist/{list_id}/add
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "external_ids": ["seed@example.com"]
}

Idempotency: Re-running the create or list-add calls is safe; the upsert key prevents duplicate records.

Always-on flow coverage

Telltide watches Emarsys Automation Center programs that run continuously, not just batch campaigns. To guarantee the seed is enrolled every time a real contact would be, the seed must satisfy whatever entry primitive the program uses.

1. Segment-entry programs. If the entry node is a Segment, edit the Segment definition and add an OR clause that matches the seed contact directly, for example field 3 (Email) equals seed@example.com. This guarantees enrollment regardless of whether the seed satisfies the original segment criteria. Keep the OR clause scoped only to the seed identifier so production targeting is unaffected.

2. Contact List-entry programs. Add the "Telltide Seeds" Contact List as an additional source on the entry node. Emarsys evaluates list membership at entry time, so the seed enters alongside the production audience.

3. External Event-entry programs (Interactions). When the program's entry is an External Event, every production payload that fires the event must also fire for the seed. Either include the seed in the same POST /api/v2/event/{eventId}/trigger call your application already makes, or fire a parallel call with the seed contact. Example payload that adds the seed alongside real recipients:

POST https://api.emarsys.net/api/v2/event/{eventId}/trigger
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "contacts": [
    {"3": "real-customer@example.com"},
    {"3": "seed@example.com"}
  ],
  "data": {
    "order_id": "ORD-12345",
    "order_total": "149.99"
  }
}

4. Data-change-entry programs. If the entry trigger fires on a contact field change (e.g., 31 flips from 2 to 1), drive the seed through the same field transition via PUT /api/v2/contact so Automation Center observes the change.

5. New-contact-entry programs. A "New contact" entry only fires once per email. To re-cover this trigger, rotate the seed local-part (e.g., seed+2026-05@example.com) and re-create the record so a fresh "New contact" event is generated.

6. Recurring filter programs. Set the seed contact's fields to satisfy the program's recurring filter (date fields, custom fields, Smart Insight lifecycle stage). On every scheduled evaluation, the seed re-enters with the rest of the filtered audience.

7. Web Extend-entry programs (Abandoned Cart, Browse Abandonment). These cannot be simulated via API alone. Drive the seed through a real browser session on the tracked site so the Web Extend library emits the cart_update or page-view event for the identified seed contact. Where possible, mirror the same event via POST /api/v2/event/{eventId}/trigger as a backup.

For every program type, also confirm the seed is not blocked by the account-level Frequency Cap (see Gotchas, below).

Profile attributes required

Seeds need:

• Email address (field 3)
• Email opt-in = 1 (field 31) - contacts with opt-in = 2 (opted out) are excluded from all marketing sends
• Values for any personalization fields used in the email template (empty fields render blank or with the configured default value)

Ensuring seeds receive the same version as real recipients

Segment-based Recipient Source: If the campaign targets a Segment, the seed must satisfy the segment's filter conditions. The simpler approach: use a Contact List as the Recipient Source alongside the segment, or ensure the seed contact's fields satisfy the segment conditions.

Dynamic content blocks: Emarsys supports dynamic content within a single campaign based on contact field values. The seed receives the block matching its own field values. Set the seed's fields to match the segment you want to monitor.

Gotchas

50-contact limit on test sends. If your "Telltide Seeds" test contact list exceeds 50 contacts, test email sends fail. Keep the test list below this limit.

Frequency Cap blocks sends. Emarsys's global account-level Frequency Cap can suppress contacts who have received too many campaigns in a set window. Seeds subject to the Frequency Cap may not receive campaigns. Check the Frequency Cap setting (account settings) and ensure seed contacts are not being blocked by it.

---

2. Ongoing / automated journeys (Automation Center / Interactions)

SAP Emarsys has two automation builders: Automation Center (for lifecycle/recurring programs) and Interactions (for real-time event-driven programs).

Automation Center entry triggers

Interactions entry triggers

---

Creating trap profiles per journey type

Welcome / onboarding (New contact entry)

• Entry: "New contact" - fires when a contact record is inserted into the database with opt-in status = 1
• Seed requirements: Email address, opt-in field (31) = 1
• How to trigger: Create a new seed contact via the API or UI. The "New contact" entry fires when the record is first created.
• Data change trigger variant: If the program uses "Data change" on the opt-in field: set opt-in to 0 first (or create without opt-in), then change it to 1 via API update to fire the trigger.

PUT https://api.emarsys.net/api/v2/contact
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "3": "seed@example.com",
  "31": 1
}

Abandoned cart (Web Extend event - Interactions)

• Trigger: Web Extend cart_update event in Interactions - fires when cart activity is detected and no subsequent purchase occurs within the configured window
• Seed requirements: Email address, opt-in = 1, Web Extend JavaScript installed on the ecommerce site
• How to trigger: The seed must browse the ecommerce site with an identified session (linked to their email via Web Extend). Add items to the cart and abandon without purchasing. The Web Extend library fires the cart_update event automatically.
• For the Interactions "Fast Abandoned Cart" tactic: The built-in tactic uses the Web Extend cart_update event. Seed must actually interact with the tracked website.
• Alternative via External Event API:

POST https://api.emarsys.net/api/v2/event/{eventId}/trigger
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "contacts": [
    {"3": "seed@example.com"}
  ],
  "data": {
    "cart_value": "95.00",
    "cart_product": "Widget Pro",
    "cart_url": "https://yourstore.com/cart"
  }
}

Replace {eventId} with the External Event ID from Account Management > Custom Events.

Browse abandonment

• Trigger: Web Extend page view event in Interactions
• Seed requirements: Email address, opt-in = 1, identified Web Extend session
• How to trigger: Same as abandoned cart - seed must browse tracked product pages while identified via Web Extend. Browser-based navigation is the most reliable approach.

Winback / re-engagement (Recurring Filter / Recurring Program)

• Entry: Automation Center Recurring Program using a filter based on behavior fields
• Filter criteria example: predict_last_purchase_date (Smart Insight/Predict-derived field) is older than 90 days AND opt-in = 1
• Seed requirements: Contact with the relevant purchase/engagement date field set to a date older than the lapse threshold

Set a date field on the seed:

PUT https://api.emarsys.net/api/v2/contact
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "3": "seed@example.com",
  "{{last_purchase_field_id}}": "2025-01-15"
}

Replace {{last_purchase_field_id}} with the numeric ID of your custom "Last Purchase Date" field (retrieved from your account's field definitions).

Post-purchase (External Event - Interactions)

• Entry: Interactions program triggered by an external event fired by the order management system
• Seed requirements: Email address, opt-in = 1, order data populated in event payload or contact data fields
• How to trigger: Call the external event API:

POST https://api.emarsys.net/api/v2/event/{eventId}/trigger
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}
Content-Type: application/json

{
  "key_id": "3",
  "contacts": [
    {"3": "seed@example.com"}
  ],
  "data": {
    "order_id": "TEST-ORD-001",
    "order_total": "149.99",
    "product_name": "Widget Pro"
  }
}

Birthday / anniversary (Date-based Recurring Program)

• Entry: Automation Center Recurring Program using a filter: Date of birth field (field 4) anniversary is today
• Seed requirements: Contact with 4 (Date of birth) field set; format YYYY-MM-DD
• Date format: ISO 8601 (YYYY-MM-DD) via API. Dates over 120 years old are rejected by the system; empty dates are ignored.

Set the birthday on the seed:

PUT https://api.emarsys.net/api/v2/contact
{
  "key_id": "3",
  "3": "seed@example.com",
  "4": "1990-04-15"
}

• For same-day testing: Set the seed's 4 (date of birth) to today's date. At the next Recurring Program evaluation, the seed matches the "anniversary is today" condition and enters the program.

---

Program validation and testing

Automation Center - no live dry run. There is no sandbox or test mode for active programs. To test, either use a demo/sandbox tenant, or create seed contacts in the live account and trigger the automation via the real entry mechanism.

Interactions - test events. For External Event-triggered Interactions programs, trigger the external event API with a seed contact to test the flow without waiting for real customer actions.

---

How to reset seeds for repeated testing

Event-triggered programs (Interactions): Fire the external event API again for the seed contact. Interactions programs support re-entry unless enrolment limits prevent it.

Recurring Filter programs (Automation Center): The program evaluates the filter on its next scheduled run. If the seed still matches the filter, it enters again on the next cycle.

New contact entry programs: Create a new seed contact (different email address) to trigger the "New contact" entry event again, since the original contact is already in the database.

---

3. Platform-specific considerations

API options

Create contact:

POST https://api.emarsys.net/api/v2/contact
X-EMS-Auth: {{escher_signature}}
X-EMS-Date: {{iso8601_basic_utc}}

Create or update contact (upsert):

PUT https://api.emarsys.net/api/v2/contact

Creates if no match found; updates if match found on key_id field.

Get contact:

GET https://api.emarsys.net/api/v2/contact/{id}

Create contact list:

POST https://api.emarsys.net/api/v2/contactlist

Add contacts to list:

POST https://api.emarsys.net/api/v2/contactlist/{id}/add

Trigger external event (Interactions):

POST https://api.emarsys.net/api/v2/event/{eventId}/trigger

Up to 200 contacts per request. Use trigger_id parameter for deduplication of repeated event calls.

API key and credentials: Account Management > API settings. Generate the API username and secret used to derive the Escher signature for the v2 API. For v3 / OAuth 2.0: Admin > Integration > API credentials.

Region-specific base URLs:

• Default: https://api.emarsys.net/api/v2/
• SAP BTP (newer deployments) may use a different base URL provided in your account provisioning documents

Rate limits

Duplicate contact handling

Email address is the default deduplication key when using key_id: "3". When PUT /api/v2/contact is called with an existing email, the existing record is updated (upsert behavior). During CSV import, the Import Wizard prompts for unique identifier fields to use for deduplication.

The Duplication Handling page (Contacts > Duplication Handling) shows contacts flagged as potential duplicates (same name, different email). You can merge or dismiss each suspected duplicate from this screen.

Case sensitivity: Email addresses during import are case-sensitive by default. User@example.com and user@example.com are treated as different identifiers. Normalize all email addresses to lowercase before import.

Platform-specific terminology

Known limitations and workarounds

Test emails limited to 50 contacts. Keep test/seed contact lists below 50 entries. For larger seed programs, use the live campaign with the seed contact included in the campaign's Recipient Source.

Test emails require existing database contacts. You cannot send a test email to an arbitrary email address if the template uses personalization tokens. Always create the seed as an actual contact record before testing.

Batch programs cannot be modified after activation. Plan the Automation Center Batch program carefully - once activated, no node changes are possible. For iterative testing, use a fresh copy of the program.

WSSE authentication is deprecated (sunset end of 2026). New integrations on the v2 API should use the Escher signing scheme (X-EMS-Auth plus X-EMS-Date). New integrations starting fresh should target the v3 API with OAuth 2.0 / OIDC. Existing WSSE-based seed management scripts should be migrated before the sunset date.

No live sandbox mode for active programs. Testing requires either a dedicated demo tenant or real seed contacts in the production account. Use the external event API to trigger Interactions programs precisely for testing purposes.

Web Extend-based triggers cannot be simulated via pure API. Abandoned cart and browse abandonment triggers that rely on Web Extend require actual browser interaction with the tracked website. Use the External Event API as a workaround for non-Web Extend implementations.