Introduction

Each method that returns lists and collections of resources can be paginated by adding to the URL the following query string parameters.

pageSize: defines the page dimension of the collection;
pageNumber: defines which page to start from;

Filtering and sorting are supported in API v1.1 by using the following query string parameters:

filterby: define the filtering expression for the requested resource;
orderby: define the sorting condition to apply to the request results;

Both parameters must be URL encoded due to the possible presence of reserved characters in the query strings.

Please contact us if you need a custom feature that might be implemented according to your specifications and needs.

Best Practices

To avoid timeout problems and improve performance, we recommend using pagination and dividing complex processes into smaller and faster ones. This way, the client application is in charge of rebuilding the large data set that would be retrieved from the smaller sets returned by the MailUp system through pagination.
URL encoding of the query string parameters is always recommended, even if in some cases the method calls can work without it.

Filtering

Resource filtering is done thanks to a dedicated expression evaluator which is capable of transforming the user-provided filter expression into the appropriate SQL statements to query the server database.
This transformation is achieved in two steps:

The expression parser evaluates the user filter string identifying operands and operators then it builds a token tree which is passed into the expression builder.
The expression builder scans the token tree and maps operands and operators to the appropriate LINQ statements which are then executed against the database to get the results.

Property accessors

Usually, resource properties can be accessed through dot notation (ex. message.id) but in some cases, when the property represents a list or an array of sub items (ex. console recipient custom fields) square bracket notation can be used (ex. recipient.Fields['name']).
In case a property is not defined on the requested resource, a suitable error message is returned describing the issue.

Supported operators

There are two supported operators' types :

Mathematical / Logical
TypeRegistry

Mathematical / Logical operators define the relation against two resource properties or between a property and a static value (ex resource.Name == 'David').
TypeRegistry operators define a specific resource property characteristic (ex. resource.Email.Contains('mailup.com')).

Mathematical and logical operators

Supported mathematical and logical operators are:

"!", unary "not": returns true if and only if its operand is false
"*", Multiply: computes the product of its operands
"/", Divide: divides its first operand by its second operand
"%", Modulo: computes the remainder after dividing its first operand by its second
"+", Add: for numeric types, + computes the sum of its two operands. When one or both operands are of type string, + concatenates the string representations of the operands
"-", Subtract: subtract the second operand from the first
"<<", binary LeftShift: shifts its first operand left by the number of bits specified by its second operand
">>", binary RightShift: shifts its first operand right by the number of bits specified by its second operand
"<", LessThan: returns true if the first operand is less than the second, false otherwise
">", GreaterThan: returns true if the first operand is greater than the second, false otherwise
"<=", LessThanOrEqual: returns true if the first operand is less than or equal to the second, false otherwise
">=", GreaterThanOrEqual: returns true if the first operand is greater than or equal to the second, false otherwise
"==", Equal: returns true if the values of its operands are equal, false otherwise
"!=", NotEqual: returns false if its operands are equal, true otherwise
"&", binary And: computes the logical bitwise AND of its operands
"^", binary ExclusiveOr: computes the bitwise exclusive-OR of its operands
"|", binary Or: computes the bitwise OR of its operands
"&&", AndAlso: performs a logical-AND of its bool operands
"||", OrElse: performs a logical-OR of its bool operands

TypeRegistry operators

TypeRegistry operators are all the type methods and properties as defined by the C# language code definition. For details on method names please refer to MSDN online documentation.
Supported type are:

"bool", System.Boolean;
"byte", System.Byte;
"char", System.Char;
"int", System.Int32;
"decimal", System.Decimal;
"double", System.Double;
"float", System.Single;
"object", System.Object;
"string", System.String;
"DateTime", System.DateTime;
"Convert", System.Convert;
"Math", System.Math;

All the supported operators can be mix-matched to fulfill the user's needs.

Type and cast definition

As far as some value casts and definitions can be done through RegistryType operators, direct casting and particular type definition (ex. a DateTime value) can be inferred directly using a specific syntax definition.
In particular:

Datetime values: can be written as #yyyy-mm-dd HH:mm:ssZ# (please note that as for ver.1.0 all date values are assumed to be in UTC timezone)
Direct cast: This can be achieved through round brackets by specifying one of the supported types. (ex. (int) double value )
Numerical type definition: can be specified by short letter suffix (ex. 1.5F define a single floating-point value, 150000L define an Int64 value). Default numerical values are supposed to be integers (Int32). The supported suffix is:
- "D": double
- "F": float
- "L": long
- "M": decimal

Examples

Request for subscribed list recipient whose email address contains 'mailup.com' sorted by 'name' descending (custom fields)

Method	URI	Filter expression	Sorting expression
GET	/Console/List/{ID_LIST}/Recipients/Subscribed	Email.Contains('mailup.com')	Fields['FirstName'] desc
Resulting URI	/Console/List/1/Recipients/Subscribed?filterby="Email.Contains(%27mailup.com%27)"&orderby="Fields%5b%27FirstName%27%5d+desc"

Request for subscribed list recipient whose first name is 'Davide' sorted by 'Email' descending

Method	URI	Filter expression	Sorting expression
GET	/Console/List/{ID_LIST}/Recipients/Subscribed	Fields['FirstName'] == 'Davide'	Email desc
Resulting URI	/Console/List/1/Recipients/Subscribed?filterby="Fields%5b%27FirstName%27%5d+%3d%3d+%27Davide%27"&orderby="Email+desc"

Request statistics for message views done by recipients whose email contains mailup ordered by view count descending

Method	URI	Filter expression	Sorting expression
GET	Message/{id_Message}/List/Views	Email.Contains('mailup')	Count desc
Resulting URI	/Message/1/List/Views?filterby="Email.Contains(%27mailup%27)"&orderby="Count+desc"

Request statistics for message views done by recipients whose email contains mailup, between 2013/01/01 and 2013/01/31 ordered by view count descending

Method	URI	Filter expression	Sorting expression
GET	Message/{id_Message}/List/Views	Email.Contains('mailup') && [Date >= #2013/01/01# && Date < #2013/01/31#]	Count desc
Resulting URI	/Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+%5bDate+%3e%3d+%232013%2f01%2f01%23+%26%26+Date+%3c+%232013%2f01%2f31%23%5d"&orderby="Count+desc"

Request statistics for message views done by recipients whose email contains mailup, in the last 24 hours ordered by view count descending

Method	URI	Filter expression	Sorting expression
GET	Message/{id_Message}/List/Views	Email.Contains('mailup') && Date >= DateTime.Now().AddDays(-1)	Count desc
Resulting URI	/Message/1/List/Views?filterby="Email.Contains(%27mailup%27)+%26%26+Date+%3e%3d+DateTime.Now().AddDays(-1)"&orderby="Count+desc"

Sorting

Sorting queries define how results should be ordered. Sorting properties are all first-level properties as defined in resource service contracts and only in particular cases (ex. recipient custom fields) second-level ones can be used.
A sorting query is represented by a string of properties and operands divided by a colon (',') and semicolon (';'). Properties that share the same sorting direction can be listed as comma-separated values (ex. name, surname desc). When a different sorting direction has to be specified, the new property list must be separated by the others with a semicolon (ex. name, surname desc; email asc).
The way the sorting query is written, determine also the priority of sorting execution, so in the case of "name desc; email asc" the results are initially ordered by name descending and then by email ascending.