Task v1.2

Sends a message to a series of subscriptions at the time provided. Automatically generates a record of contact for each recipient.

What can I do with task?

The task attributes are useful for describing the task's state and when particular events occurred.

  • Use id, cancelled and/or completed to check a task's status.
  • You can see when the task was cancelled or completed with endtime.
  • Combining the channel filter with another filter can give you a powerful collection of scheduled, cancelled or completed tasks.
  • Filter by list_id to see which tasks targeted a particular list.
  • If completed, tasks will return some concise performance analytics.

GET /task or /task/:id

AttributeTypeFilterSortDescription
id

int

Yes

Yes

Unique ID of the task.

cancelled
boolYesNoWhether the task was cancelled.
channel

enum

Yes

No

Send channel: "email" or "sms".

completed
boolYesNoWhether this task has completed.
emailuniquebounces
int/null*NoNoNumber of unique bounces - email channel specific.
emailuniqueclicks
int/null*NoNoNumber of unique clicks - email channel specific.
emailuniqueopens
int/null*NoNoNumber of unique opens - email channel specific.
emailuniqueunsubscriptions
int/null*NoNoNumber of unique unsubscriptions - email channel specific.
emailuniquecomplaints
int/null*NoNoNumber of unique complaints - email channel specific.
endtime

decimal/null

No

Yes

Timestamp at which the task finished or was cancelled.

list_id
int/nullYesNoID of the target list.
message_id
intYesNoID of the message associated with this task.
name
stringYesYesName of the task.
rate
int/nullNoNoIf 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/nullNoNoID of the target search; defaults to null.
size

int

No

No

Number of recipients at time of task creation.

smsuniquebounces 
int/null*NoNoNumber of unique bounces - sms channel specific.
splittest_id
int/nullNoNoThe 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.

HEAD /task or /task/:id

AttributeTypePresenceDescription
id

int

Optional

Unique ID of the task.

cancelled
boolOptionalWhether the task was cancelled.
channel

enum

Optional

Send channel: "email" or "sms".

completed
boolOptionalWhether this task has completed.
list_id
int/nullOptionalID of the target list.
message_id
intOptionalID of the message associated with this task.
name
stringOptionalName of the task.

POST /task

AttributeTypePresenceDescription
channel

enum

Required

Send channel: "email" or "sms".

list_id
int/nullRequired*ID of the target list.
message_id
intRequiredID of the message associated with this task.
name
stringRequiredName of the task.
rate
int/nullOptionalIf 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/nullRequired*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.

PUT /task or /task/:id

AttributeTypePresenceDescription
id

int

Required

Unique ID of the task.

cancelled
boolOptionalWhether the task was cancelled.
list_id
int/nullOptional*ID of the target list.
name
stringOptionalName of the task.
scheduledtime

decimal

Optional

Timestamp at which the task was scheduled to start.

search_id
int/nullOptional*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.

DELETE /task or /task/:id

This method is not supported.

Error codes

There are no error codes for this endpoint.

Examples

Have you seen our example of this endpoint being used with other endpoints?

JSON response

{
    "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,
}