Emarsys

SAP-owned omnichannel customer engagement platform. Zeotap syncs contacts, triggers external events, and manages contact list membership via the Emarsys REST API.

Prerequisites

• An Emarsys account with API access enabled
• An API username and secret key (generated in Emarsys Management > Security Settings)
• For contact list operations: an existing contact list ID
• For external events: a configured external event ID in Emarsys

Permissions

Your Emarsys API user must have permissions for the endpoints you intend to use:

• Contacts: Read/write access to the Contacts API
• Contact Lists: Access to contact list management endpoints
• External Events: Permission to trigger external events

Authentication

Emarsys uses WSSE (Web Services Security) authentication. Each API request includes a cryptographic token generated from your username and secret.

1. In Emarsys, navigate to Management > Security Settings
2. Create a new API user or use an existing one
3. Copy the API Username (format: account_name001)
4. Generate a new API Secret and save it immediately (it cannot be retrieved later)
5. In Zeotap, paste the username into the API Username field
6. Paste the secret into the API Secret field

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Required fields depend on the selected Object Type:

Default Destination Fields

Contacts

key_value, 1 (First Name), 2 (Last Name), 3 (Email), 4 (Date of Birth), 5 (Gender), 15 (Salutation), 31 (Opt-In), 46 (Mobile)

External Events

external_id, data (JSON event payload)

How It Works

Contact Syncs

1. Zeotap maps your source columns to Emarsys field IDs
2. The key_value field is mapped to your configured Key Field ID (e.g. field 3 for email)
3. Rows are batched into groups of up to 1,000 contacts per API call
4. In upsert mode, contacts are created if they do not exist (create_if_not_exists=1)
5. In update mode, only existing contacts are modified
6. Per-row errors are reported individually without failing the entire batch

Contact List Syncs

1. Zeotap extracts the key value from each row
2. In add/upsert mode, contacts are added to the specified list
3. In remove mode, contacts are removed from the list
4. In mirror mode, new/changed contacts are added and removed contacts are deleted from the list
5. Rows are batched into groups of up to 10,000 contacts per API call

External Event Syncs

1. Each row triggers the configured external event for one contact
2. The external_id field identifies which contact receives the event
3. Additional mapped fields are passed as event data

Emarsys Field IDs

Emarsys uses numeric field IDs instead of field names. Common system fields include:

Custom fields have higher numeric IDs. Find your field IDs in Emarsys under Management > Field Editor.

Rate Limits

Emarsys enforces a rate limit of 1,000 API requests per minute per API key. Zeotap batches contacts (up to 1,000 per request) and handles rate limiting with automatic retry and exponential backoff.

Best Practices

• Use email as the key field (key_field_id=3) for the most reliable contact matching
• Prefer upsert mode for contacts to avoid errors when contacts do not exist
• Map only the fields you need — Emarsys PUT requests replace all included field values
• Use contact lists for audience syncs — the contact list endpoints support add, remove, and mirror operations
• Batch external events carefully — each event is a separate API call, so large volumes may hit rate limits
• Verify field IDs in the Emarsys Field Editor before configuring your sync

Troubleshooting

Authentication failed: invalid username or secret

Verify your API username and secret in Emarsys under Management > Security Settings. The secret cannot be retrieved after creation — if lost, generate a new one.

Contact not found during update

When using update sync mode, contacts must already exist in Emarsys. Switch to upsert mode to create contacts automatically.

Invalid field ID error

Emarsys uses numeric field IDs (e.g. 3 for email). Verify your field IDs in Management > Field Editor. Custom fields have higher numeric IDs.

Rate limit exceeded (429 errors)

Zeotap handles rate limiting automatically with exponential backoff. If you consistently hit limits, reduce sync frequency or contact Emarsys support to increase your API quota.

Contact list not found

Verify the Contact List ID is correct. Navigate to Contacts > Contact Lists in Emarsys to find the numeric list ID.

External event trigger failed

Ensure the external event ID is valid and the event is active in Emarsys. Check that the contact identified by external_id exists in the system.

Duplicate contact errors

Use a unique field as your key field (email is recommended). Non-unique key fields can cause conflicts during upsert operations.

Date field format errors

Emarsys expects dates in YYYY-MM-DD format. Ensure your source data matches this format for date fields.