Task v1.2
Sends a message to a series of subscriptions at the time provided. Automatically generates a record of contact for each recipient.
Sends a message to a series of subscriptions at the time provided. Automatically generates a record of contact for each recipient.
The task attributes are useful for describing the task's state and when particular events occurred.
id
, cancelled
and/or completed
to check a task's status.cancelled
or completed
with endtime
.channel
filter with another filter can give you a powerful collection of scheduled, cancelled
or completed
tasks.list_id
to see which tasks targeted a particular list.completed
, tasks will return some concise performance analytics.Attribute | Type | Filter | Sort | Description |
---|---|---|---|---|
id | int | Yes | Yes | Unique ID of the task. |
cancelled | bool | Yes | No | Whether the task was cancelled. |
channel | enum | Yes | No | Send channel: "email" or "sms". |
completed | bool | Yes | No | Whether this task has completed. |
emailuniquebounces | int/null* | No | No | Number of unique bounces - email channel specific. |
emailuniqueclicks | int/null* | No | No | Number of unique clicks - email channel specific. |
emailuniqueopens | int/null* | No | No | Number of unique opens - email channel specific. |
emailuniqueunsubscriptions | int/null* | No | No | Number of unique unsubscriptions - email channel specific. |
emailuniquecomplaints | int/null* | No | No | Number of unique complaints - email channel specific. |
endtime | decimal/null | No | Yes | Timestamp at which the task finished or was cancelled. |
list_id | int/null | Yes | No | ID of the target list. |
message_id | int | Yes | No | ID of the message associated with this task. |
name | string | Yes | Yes | Name of the task. |
rate | int/null | No | No | If specified, the maximum rate at which the individual messages comprising the task will be sent; expressed as messages per hour. |
scheduledtime | decimal | No | Yes | Timestamp at which the task was scheduled to start. |
search_id | int/null | No | No | ID of the target search; defaults to null. |
size | int | No | No | Number of recipients at time of task creation. |
smsuniquebounces | int/null* | No | No | Number of unique bounces - sms channel specific. |
splittest_id | int/null | No | No | The associated split test id. |
cdate | decimal | No | Yes | Creation timestamp. |
* emailuniquebounces
, emailuniqueclicks
, emailuniqueopens
, emailuniqueunsubscriptions
, emailuniquecomplaints
, smsuniquebounces
are always returned for both 'sms' and 'email' channels. NULL
values will be returned if the statistic does not apply to the channel.
scheduledtime
is the desired start time, not the time at which the system actually started to process the task. endtime
will return null
until the task has completed
or is cancelled
.
The size
attribute is a count of subscriptions the task found at the point of creation. The amount of recipients (and contact records created) can be different if any subscriptions were added or removed between cdate
and endtime
.
A user may not have permission to view all messages. In this case, only tasks with a message_id
created by the user are returned.
Attribute | Type | Presence | Description |
---|---|---|---|
id | int | Optional | Unique ID of the task. |
cancelled | bool | Optional | Whether the task was cancelled. |
channel | enum | Optional | Send channel: "email" or "sms". |
completed | bool | Optional | Whether this task has completed. |
list_id | int/null | Optional | ID of the target list. |
message_id | int | Optional | ID of the message associated with this task. |
name | string | Optional | Name of the task. |
Attribute | Type | Presence | Description |
---|---|---|---|
channel | enum | Required | Send channel: "email" or "sms". |
list_id | int/null | Required* | ID of the target list. |
message_id | int | Required | ID of the message associated with this task. |
name | string | Required | Name of the task. |
rate | int/null | Optional | If specified, the maximum rate at which the individual messages comprising the task will be sent; expressed as messages per hour. |
scheduledtime | decimal | Required | Timestamp at which the task was scheduled to start. |
search_id | int/null | Required* | ID of the target search; defaults to null. |
All tasks are charged at send time, not when the task is created or modified. It is the sender's responsibility to ensure there is sufficient credit, quota or overage available.
If the specified value of scheduledtime
is less than the current unix timestamp, it will automatically be set to the current unix timestamp.
Attribute | Type | Presence | Description |
---|---|---|---|
id | int | Required | Unique ID of the task. |
cancelled | bool | Optional | Whether the task was cancelled. |
list_id | int/null | Optional* | ID of the target list. |
name | string | Optional | Name of the task. |
scheduledtime | decimal | Optional | Timestamp at which the task was scheduled to start. |
search_id | int/null | Optional* | ID of the target search; defaults to null. |
*Exactly one of: list_id
, search_id
must be non-null.
You cannot set a task to be cancelled
once it has been completed
.
This method is not supported.
There are no error codes for this endpoint.
Have you seen our example of this endpoint being used with other endpoints?
{ "id": 2209, "cancelled": false, "channel": "email", "completed": false, "emailuniquebounces": 3, "emailuniqueclicks": 100, "emailuniqueopens": 1000, "emailuniqueunsubscriptions": 2, "emailuniquecomplaints": 0, "endtime": null, "list_id": 123, "message_id": 12345, "name": "Example task", "rate": 5000, "scheduledtime": 1234966741, "search_id": null, "size": 1234, "smsuniquebounces": null, "splittest_id" null, "cdate": 1234966741, }