REST API: Message Filters

For any GET request to the /api/messages endpoint, you may optionally specify one or more filters submitted as request query parameters to be applied to the list of returned messages.

A filter is a query parameter whose name is the field to be filtered on and whose value is a JSON object with the following format:

{
  o: string
  v: boolean|number|string|array
}

Where o is the operator to be applied (see valid operators below) and v is the value(s) to be compared against. If v is a JSON object then it will be serialized to a JSON string and treated as a simple string value. If v is a JSON array then each of its elements must be boolean, number or string otherwise it is serialized to a string and treated as such. A filter with an array value will match any message that satisfies any one of the values in the array with the given operator (i.e. the values in the array are OR'd together). You may also submit the same parameter name more than once in the query. Doing this will AND the filters together.

A shortcut is provided for the equality filter. If testing for equality, you can just use field=value as the query parameter. This will be converted to a proper filter object for you.

See the list of special fields below. Any field specified that is not listed as special is considered to be the name of an email header to be filtered on.

These ideas are best explained by example.

Find all messages currently stored from my client scope (i.e. no filters applied):

/api/messages?clnt=127.0.0.1

Find all messages sent from john@doe.com:

/api/messages?clnt=127.0.0.1&sender=john%40doe.com

Find all messages sent from john@doe.com and bcc to mary@doe.com:

/api/messages?clnt=127.0.0.1&sender=john%40doe.com&bcc=mary%40doe.com

Find all messages sent after Jan 1, 2015:

/api/messages?clnt=127.0.0.1&sent=%7B%22o%22%3A%22%3E%3D%22%2C%22v%22%3A%222015-01-02%2000%3A00%3A00%22%7D

The value for sent is the url encoded JSON object that looks like this:

{"o":">=","v":"2015-01-02 00:00:00"}

Find all messages sent from bob@example.com or mary@example.com:

/api/messages?clnt=127.0.0.1&sent=%7B%22o%22%3A%22%3D%22%2C%22v%22%3A%5B%22bob%40example.com%22%2C%20%22mary%40example.com%22%5D%7D

Since we want to OR the values, we must encode our filter. The sent value is the encoded JSON string:

{"o":"=","v":["bob@example.com", "mary@example.com"]}

Find all messages sent to both gary@business.com and pat@business.com:

/api/messages?clnt=127.0.0.1&_for=gary%40business.com&_for=pat%40business.com

Since we're ANDing the values, we can use the shortcut equality filters.

Limitations of Filters

Though flexible, these filters do not allow for every possible filter. For example, it's currently not possible to query for the following:

Return all messages sent by john@doe.com or sent to mary@business.com.

A future version of psmtp may address this. Instead, you would need to filter the messages client side after downloading them all. This is not ideal and if you need these kinds of filters quite often then open a ticket and let me know and I'll see about perhaps tackling the issue.

Special Fields

The fields in the table below are recognized by psmtp. Any field not listed in this table is assumed to be the name of an email header whose value you wish to filter on.

Field Name	Meaning
sender	The email address (only) of the sender of the email
sent	A timestamp representing when the email was sent
to	The email address (only) of a recipient in the to field
cc	The email address (only) of a recipient in the cc field
bcc	The email address (only) of a recipient in the bcc field
_for	Matches if the email address is a to, cc, or bcc recipient; converts to (to = <val> OR cc = <val> OR bcc = <val>)
has_attachment	Allows to filter messages based on if they have or don't have attachments

All fields are treated as strings when comparing except for the following:

• The sent field is a timestamp and is compared as such. Values to compare against must be provided in the form: yyyy-mm-dd hh:mm:ss[.nnn]
• The has_attachment field is a boolean. The value is parsed as a boolean and then used for the comparison. So pass true (case insensitive) to filter on messages with attachments or any other value to filter on messages without attachments.

Supported Operators

The following operators may be used in your filters:

Operator	Meaning
=	equals
!=	does not equal
>	greater than
<	less than
>=	greater than or equal to
<=	less than or equal to

Note: Some operators are not valid for certain field types. Namely, boolean types (i.e. has_attachment) only support the equals operator; trying to use any other will cause an error.