Sending model

Sending

Sending status

The Sending may have one of following statuses, which may be grouped into initial states, execution steps and the final outcomes:

initial states:

draft - When API client didn't't define the schedule (or has draft: true flag)

scheduled - When scheduled to be sent at specific time by API client

Sending may have status changed from draft to scheduled and vice versa, as long as the execution haven't started yet.

execution steps:

preparing - Building Dispatches for Recipients and Audience members

prepared - Dispatches are built, ready for transmission

transmitting - Dispatches are being transmitted

final outcomes:

transmitted - When the Dispatches have been transmitted

skipped - When no recipients could be resolved for it (for example, Audience may lose its members over time).

cancelled - When cancelled by API client at any point of execution (see: Sending cancellation).

failed - When the execution couldn't be finished in about 20 minutes after the desired time

Whenever Sending is cancelled or failed, it cannot be rescheduled again.

Sending payload

A payload for a new/scheduled Sending is signically different from a persisted Sending record:

Sending::Payload

Examples

Payload for Sending without schedule to audience defined by given conditions:

{
  // Schedule is not provided, so message will not be scheduled
  "audience": {
    "type": "inline",
    "conditions": [
      {
        "condition_group": "member_properties", "field": "first_name", 
        "operator": "match", "value": "Piotr"
      }
    ]
  }
}

Payload for scheduling a Sending 2 days from now to members of an Audience defined by ID and 2 arbitrary recipients:

{
  "schedule": { "type": "relative", "in": "2 days" },
  "audience": { "type": "inline", "id": 15 },
  "recipients": [
    { "member_id": 150, "properties": { "name": "Piotr" } },
    { "email": "jan@example.com", "properties": { "name": "Jan" } }
  ]
}

Defining recipients

There are two methods to define recipients of the sending:

audience - members of the target Audience will be used as recipients (see below)

recipients - inline receivers (see: here)

Both methods can be used at the same time.

Audience recipients

Sending Audience may be defined:

by id (reference audience type)

by conditions (inline audience type)

See: DMP docs

Example of providing Audience by reference:

{ 
  "type": "inline", 
  "id": 532 
}

Example of providing Audience by inline conditions:

{ 
  "type": "inline",
  "conditions": [{
    "condition_group": "member_properties", "field": "first_name", 
    "operator": "match", "value": "Piotr"
  }]
}

Inline recipients

Recipient may be a MPC member (identified by member_id) or an arbitrary sending receiver - identified by at least one of: msisdn, email or push.

Recipient

Example:

{
  "member_id": 150,
  "msisdn": "4740769126",
  "email": "recipient@example.com",
  "app_token": "c6OE_joK28g:APA91bFkT5fzhdWJMJswPo3btVLxtMmhi7jKdOE_VL1IhkSmuoz3iEQMg4Cq",
  "properties": { "first_name": "Piotr" }
}

MPC member recipient

When member_id is provided, other identifiers will be ignored and actual identifiers for sending execution will be fetched from MPC member's data (for example, for sms channel member's msisdn will be used as a sending receiver).

Merge-properties for template will be fetched from MPC Members - but may be extended/replaced with provided properties.

Arbitrary recipient

Without member_id, at least one identifier relevant to message's channels definition is required.

For example, if sms and email channels are defined on message, msisdn or email is required.

Given properties will be used as template's merge-tags.

Channels preference

When message has multiple channels, it is possible to select which channels should be used for delivering the Message to the recipient and specify the preferred order (priority) with channels_preference attribute.

For example, "channels_preference": ["sms", "email"] means that sms and email channels should be used for Sending and sms is preffered.

Schedule

The schedule is optional - when not provided, sending will not be scheduled (will have draft status).

Example of an immediate schedule:

{ "type": "immediate" }

Example of an absolute schedule:

{ "type": "absolute", "at": "2020-10-18T10:59:32.340Z" }

Example of a relative schedule:

{ "type": "relative", "in": "5 minutes" }

Format of `in` parameter

You can provide number of time units the Sending will be scheduled at in format described by following regex:

Examples: 30 minutes, 1 day 5 months

Prescheduling

Potentially Sendings may have very large Audiences assigned, so it may take some time to build Dispatches for all of them.

Therefore, by providing prescheduled: true schedule param, the preparation will start 5 minutes before the actual transmission to speed up the sending execution.

Sending model

Sending model#

Sending status#

Sending payload#

Examples#

Defining recipients#

Audience recipients#

Inline recipients#

MPC member recipient#

Arbitrary recipient#

Channels preference#

Schedule#

Format of in parameter#

Prescheduling#

Sending model

Sending status

Sending payload

Examples

Defining recipients

Audience recipients

Inline recipients

MPC member recipient

Arbitrary recipient

Channels preference

Schedule

Format of `in` parameter

Prescheduling