Sending model

Sending

Sending status

The Sending may have one of following statuses, which are grouped into draft, scheduled and finished types.

Status	Type	Editable?	Cancellable?	Description
`draft`	`draft`	yes	no	When API client didn't define the schedule (or has `draft: true` flag)
`scheduled`	`scheduled`	yes	no	When scheduled to be sent at specific time by API client
`preparing`	`scheduled`	no	yes	Building Dispatches for Recipients and Audience members
`prepared`	`scheduled`	no	yes	Dispatches are built, ready for transmission
`transmitting`	`scheduled`	no	yes	Dispatches are being transmitted
`transmitted`	`finished`	no	no	When the Dispatches have been transmitted
`cancelled`	`finished`	no	no	When cancelled by API client
`failed`	`finished`	no	no	When the execution couldn't be finished
`skipped`	`finished`	no	no	When no recipients could be resolved for it (for example, Audience may lose its members over time).

Sending may have status changed from draft to scheduled and vice versa and is editable during this stage.

When processing starts (status >= preparing), it may only be cancelled.

And after it reaches one of statuses of finished type, it cannot be modified anymore.

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