Retrieve Messages

Retrieve the messages you have sent or received.

Scheduled messages are available for retrieval only after the delivery date.

All the parameters are optional. If a value is not supplied for filter, the messages are not filtered.

Messages can be filtered by supplying query clauses in the filter parameter. Each clause has the form name=value where name is the name of a filter field and value is a valid value for that field. A value for a field is optional. Include a clause for a field in the filter only when there is a need to fetch messages that match some value for that field. For a numeric filter field, you can also use the less than operator (<).

If present, the filter value must have at least one clause, but it can contain a combination of clauses. Multiple clauses are separated with the & symbol. Semantically, multiple clauses form a logical conjunction.

For example, if you want to list all messages that were sent as part of a particular submission, your filter contains two clauses and will look something like this

type%3DSENT&submission.id%3D1-00000000000522347562

Because filter is a request parameter, it is important to note that the value for this parameter must be URL encoded. In particular, the = encodes to %3D and the & encodes to %26. Note that you do not have to encode the < character.

Using the previous example to illustrate; after encoding and encasing it, the clauses are transformed into a request that looks like this

GET /v1/messages?filter=type%3DSENT%26submission.id%3D1-00000000000522347562

If the field name or the field value of a clause is not valid, a bad_request error is returned instead of the usual result. The detail field of this error provides more information about the problem.

The table below lists the fields available for filtering