The export events functionality is designed to allow integrators to call a single service to retrieve events for activity across the whole of Dotdigital instead of having to retrieve data from multiple services. This greatly simplifies getting data out of Dotdigital.

How it works

The Events API allows you to define one or more subscriptions, to a maximum of five, that specify which events you would like capturing for retrieval to facilitate data synchronization with one or more systems.

Once subscriptions are made active, we start capturing and storing the specified events, so that you can then retrieve these events by calling the Retrieve events call on a regular basis to sync the captured events to your platform(s).

🚫

We cannot sync historic events

We can only capture events that occur after a subscription is made active. It may take up to 5 minutes before we start capturing events.

Subscriptions

To get started, you must register a subscription using the Create subscription call. Each subscription must have a unique name and by default is created as inactive if you don't specify otherwise.

Event subscriptions

You must specify which event types you want to capture for the subscription, and optional filters to narrow these events down further.

🚧

Only subscribe to what you need

To minimize processing overheads on all platforms involved, ensure that you only subscribe to those events you require, and, where possible, further refine the selection using filters.

Subscription status

The status of a subscription is returned and set using the status field. The field can have the following values and subsequent affects on the subscription:

❗️

We suspend inactive subscriptions after 30 days

We monitor the calls to Retrieve events for each subscription to establish if they are still being used or not. If we don't see any calls to Retrieve events for a subscription within 30 days then we automatically set the status to inactive for that subscription.

This means events capture stops and data loss will likely occur.

Retrieving events

Periodically you must call Retrieve events for each active subscription.

The system uses checkpoints to track when events have been synced.

1. For a subscription, initially call Retrieve events without the checkPoint parameter. This retrieves the earliest events captured for the subscription and returns a checkPoint which you must store.
2. Store the retrieved events for processing later.
3. On subsequent calls to Retrieve events, you must pass the previous checkPoint value so we know to retrieve events since the last successful call.

🚧

Passing a checkPoint value clears data

Once you have sent the checkPoint for a page of events they are removed from the queue, so you must not try to retrieve the next page of events using the checkPoint value until you have successfully stored the retrieved page of events.

If we return no events in the events array then you have received all the currently queued events. Store the checkPoint and back off for a period of time. Use the stored checkPoint next time you want to sync to resume from where you left off.

Retrieving files and other large content

Our events are limited to 900KB in size to ensure they remain a manageable size for processing and handling. If the content of a field such as an attached file or a large message can exceed this limit then instead of passing the data in the event itself we will instead pass a LOB Id (Large OBject Identifier). This LOB Id can be used in with the Retrieve large object call to retrieve the actual data.

Events

Event families

The following families of events exist:

• Contacts
  • contact.created
  • contact.removed
  • contact.updated
  • contact.membershipUpdated
  • contact.consentAdded
  • contact.preferenceUpdated
• Messages
  • message.sent
  • message.received
  • message.status
• Interactions
  • interaction.click
  • interaction.pushClick
  • interaction.socialShare
  • interaction.unsubscribe
• Insight data
  • insightData.collectionCreated
  • insightData.collectionRemoved
  • insightData.set
  • insightData.removed

The event envelope

Each event will be placed in a standardized envelope to make handling the event simple by providing common attributes for events such as id, type, account and event date.

The envelope schema is:

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.created",
  "data": {
		<< Event data here >>    
  }
}

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.created",
  "data": {
    "contactId": 321332,
    "identifiers": {
      "email": "[email protected]",
      "mobileNumber": "447123123123",
      "customId1": "1234dcf"
    },
    "channelProperties": {
      "email": {
        "emailType": "Html",
        "optInType": "Double",
        "status": "notSubscribed"
      },
      "sms/mms/rcs": {
        "countryCode": "GB",
        "status": "notSubscribed"
      },
      "whatsApp": {
        "status": "notSubscribed"
      }
    },
    "dataFields": {
      "firstName": "John",
      "lastName": "Doe",
      "gender": "male",
      "brandFan": true,
      "age": 21,
      "lastPurchasedDate": null
    }
  }
}

Contact events

contact.created

Contact Created

Triggered when a new contact is created / added to the account.

• All identifiers are sent to allow correlation.
• All data fields are included.
• All channel properties are included.
• null values are sent for fields that have no value.

Event data fields

These are the fields in the data field of the event envelope

Example

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.created",
  "data": {
    "contactId": 321332,
    "identifiers": {
      "email": "[email protected]",
      "mobileNumber": "447123123123",
      "customId1": "1234dcf"
    },
    "channelProperties": {
      "email": {
        "emailType": "Html",
        "optInType": "Double",
        "status": "notSubscribed"
      },
      "sms/mms/rcs": {
        "countryCode": "GB",
        "status": "notSubscribed"
      },
      "whatsApp": {
        "status": "notSubscribed"
      }
    },
    "dataFields": {
      "firstName": "John",
      "lastName": "Doe",
      "gender": "male",
      "brandFan": true,
      "age": 21,
      "lastPurchasedDate": null
    }
  }
}

contact.removed

Contact Removed

Triggered when a contact is removed from the account, when an API or manual action deletes a contact.

• All identifiers are sent to allow correlation.

Event data fields

These are the fields in the data field of the event envelope

Example

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.removed",
  "data": {
    "contactId": 321332,
    "identifiers": {
      "email": "[email protected]",
      "mobileNumber": "447123123123",
      "customId1": "1234dcf"
    }
  }
}

contact.updated

Contact Updated

Triggered when a contact is updated; changes covered are with identifiers, data fields and channel properties.

• All identifiers are sent to allow correlation.
• All data fields are included.
• All channel properties are included.
• null values are sent for fields that have no value.

Event data fields

These are the fields in the data field of the event envelope

Example

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.removed",
  "data": {
    "contactId": 321332,
    "identifiers": {
      "email": "[email protected]",
      "mobileNumber": "447123123123",
      "customId1": "1234dcf"
    }
  }
}

Message events

message.sent

Message sent

Triggered when a message is sent on any channel.

Event data fields

These are the fields in the data field of the event envelope

Examples

{
  "id": "",
  "accountId": 12345,
  "processedDate": "",
  "eventDate": "",
  "type": "contact.created",
  "data": {
    "messageId": "3343556",
    "channel": "email",
    "to": {
      "contactId": 12345,
      "recipient": "[email protected]",
      "identifiers": {
        "email": "[email protected]",
        "mobileNumber": "447123123123",
        "customId1": "1234dcf"
      }
    },
    "from": "[email protected]",
    "campaignDetails": {
      "id": 245334,
      "name": "Special offer promo",
      "type": "standard"
    },
    "message": "<Email body>",
    "channelData": {
      "sendId": 47474874,
      "subject": "Don't miss out of this great offer!",
      "sendStatus": "sent",
      "sendStatusReason": ""
    }
  }
}