Task Endpoint | Sign-Up.to Permission Marketing API

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

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.

HEAD /task or /task/:id

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.

POST /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.

PUT /task or /task/:id

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.

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