ToC

Introduction

Motivation

As XQueue Maileon is a professional tool for sending marketing mails to recipients (called contacts in the following document), it is essential to select the right targetgroups. Contacts are organized in the following manner:

Contact pool:

Contactfilters:

Targetgroups:

As many deep integrations allow selecting contacts externally e.g. by specifying some rules in a CRM, the fallback is to mark those contacts in Maileon with a special contactfield. However, with the REST API it is also possible to create a matching contactfilter in Maileon itself.

Limits and Limitations

Most contactfilters are created once and reused in subsequent mailings. However, some are also used for just one (or very few) mailings. If the targetgroup and its contactfilter is not removed afterwards, the overview about contactfilters can be very confusing. Also creating filters with too many rules is not recommended. While users creating contactfilters manually will not create filters with 100 rules, this can easily happen in automated processes. Those filters can be slow to evaluate and hard to maintain. Thus, the following limits are to be followed:

• Each newsletter account can only have 100 contactfilters

• Each contactfilter can have 100 rules at most

Regarding the expressions of contactfilters, the filters created using the REST API have some limitations, e.g. geographic selections are not possible at the moment. The following operations are implemented so far:

• Adding contacts

• Removing contacts

• Creating an intersection

• Selecting a sample

The following selections are implemented:

• By contactfield value

  • Custom fields must be spelled exactly as created in Maileon

  • Standard field values (string, if not annotated):

    • address

    • birthday (date)

    • city

    • country

    • firstname

    • gender (m or f)

    • hnr

    • lastname

    • fullname

    • locale (xx or xx_XX)

    • nameday (date)

    • organization

    • region

    • state

    • salutation

    • title

    • zip

• By response information

• By targetgroup or contactfilter affiliation

• By contact event (transaction) value

• By contact preference value

Data Format

Contactfilters are submitted in a JSON format. The basic concept is that a filter contains a ordered list of rules. The first rule defines a startset, e.g. an empty set, while the subsequent rules have the resulting set of the previous rule as input.

The format has been specified as JSON Schema and can be downloaded here:

Open

Please note that the date format is specified by ISO8601 and values like 1985-04-12T23:20:50.525Z or 1985-04-12 are valid.

The basic structure contains the filter name and a set of at least one rule, e.g.:

The first rule has to specify a startset which can be one of “empty”, “all”, or “active”. The operation can be one of “add”, “remove”, “intersection”, or “sample”. Not every operation makes sence with each startset, e.g. is “remove” not possible for startset “empty”. Refer to the schema or the Maileon UI for possible combinations of operations and sets. A Valid rule is for example:

Operations “sample” has only a selection containing a type (“fixed” or “percental”) and a value (integer > 0 and for percental values <= 100). Examples for rules are:

The set operations “add”, “remove” and “intersection” require more parameters. First, they require a selection base, which can be one of “contactfield”, “response” or “list_or_filter_affiliation”. Then, a criterion is specified which is evaluated based on the selection base.

For “contactfield” the criterion contains a field name, an operation to compare values and the value to check the content of the contactfield against. Make sure to fit the JSON datatype to the contactfield datatype. If the contactfield is of type String, use a String, if it is an integer, us an integer.

Example:

For “response” the criterion can have a type of “sent”, “bounces”, “opens”, “opens_unique”, “clicked”, “clicked_unique”, “replies”, “personalization_error”, “subscriptions”, or “unsubscriptions”.

While “subscriptions” and “unsubscriptions” have only a value of type Boolean, all others can be compared using “equals”, “notequals”, “greater”, “greaterequals”, “smaller”, “smallerequals”, “between” or “notbetween”. Again, not all combinations make sense and while “between” and “notbetween” require an array of two values, the other functions require one value of the correct type.

Examples:

For “list_or_filter_affiliation” the criterion can be of type “contactfilter” or “targetgroup”, an operation and must contain a value of type integer/long if a contactfilter or targetgroup that exists in the newsletter account.

Example:

An example of a complex contactfilter can be downloaded from here:

Open

Filters based on Contactfields in Detail

Contactfield rules should have the following structure:

Attribute “selection_base” must be set to “contactfield” constant and denotes that such rules are based on contactfields. Mandatory attribute.

Attribute “field_name” must contain the name of an existing contactfield. Standardfields are written in small letter version of the regular standard fields (i.e. “firstname” instead of “FIRSTNAME”). Customfields need to be written exactly as created in Maileon. Mandatory attribute.

Attribute “operation” supports following values depending on the data type of attribute :

• For numerics: {equals, notequals, greater, greaterequals, smaller, smallerequals, between, notbetween, empty, notempty}

• For strings: {equals, notequals, ends_with, starts_with, contains, notcontains, empty, notempty, starts_with, ends_with, includein, notincludein, includein_like, includein_url}

• For booleans: {equals, notequals, empty, notempty}

• For date and timestamp: {equals, notequals, greater, greaterequals, smaller, smallerequals, empty, notempty, between, notbetween }

Depending on the cardinality of the given operation, the attribute “value” :

• Might be absent

• Contain one value

• Contain two values as a JSON array

• Contain a variable list of values as a JSON array

Filters based on Contact Events

Since 20.08.2021 the scope of rules has been extended and supports to create contactfilter based on contact events.

Two types of such rules are supported:

• rules with condition on complete contact event like “select contacts for which number of required contact events equals 3”

• rules with condition on contact event attribute like “select contacts for which value of attribute in selected contact event is contains ‘xqueue’”

Contact event based rules should have the following structure:

Attribute “selection_base” must be set to “contactevent” constant and denotes that such rules are based on contact events. Mandatory attribute.

Attribute “event_name” must contain the name of existing contact event type in Maileon. Mandatory attribute.

Attribute “attribute_name” must contain either a valid attribute name of the contact event type (attributes of type JSON are NOT allowed to be used, here) or one of the following constant values:

• “#count” – denotes that the selection condition is set on the number of contact events.

• “#created” – denotes that the selection condition is set on timestamp when contact event appeared.

Attribute “operation” supports following values depending on the data type of attribute :

• For numerics: {equals, notequals, greater, greaterequals, smaller, smallerequals, between, notbetween, empty, notempty}

• For strings: {equals, notequals, endswith, startswith, contains, notcontains, empty, notempty }

• For booleans: {equals, notequals, empty, notempty}

• For date and timestamp: {equals, notequals, greater, greaterequals, smaller, smallerequals, empty, notempty, between, notbetween}

Depending on the cardinality of the given operation, the attribute “value” :

• Might be absent

• Contain one value

• Contain two values as a JSON array

Example JSON to create a contact filter with certain conditions:

Filters based on Contact Preferences

Since 10.02.2022 a new functionality to create contact Filter Rules based on contact Preferences has been added.

Contact Preferences provide a simple functionality to represent relation between contact and some Area of Interests and uses a simple Boolean logic (e.g. ether contact is interested in something, or not interested or it is unknown). Inside of Maileon Contact Preferences are organized into categories and completely managed by users in Maileon User interface or over API.

Preferences and categories have mandatory names. Names of preferences are unique within the category, to which they are assigned.

As an example consider the following category - “Sports”. Let us assume that its has following preferences: Football, Basketball, Racing. A contact might have the following preferences assigned:

• “Football” – true

• “Basketball” – false

• “Baseball” - undefined

Due to the Boolean-based logic of how preferences are organized it is possible to Filter Contacts in the Contact Filter Rules based on their preferences using the following operators:

• Contact preference value equals

• Contact preference value not equals

• Contact preference value is defined

• Contact preference value is undefined

The Contact filter rules that can be created over API based on contact preferences have the following structure as described below.

To create a contact filter rule based on Contact Preference, the “selection_base” parameter has to be defined as “contactpreference”.

The criterion should contain following parameters:

• “category_name” – name of preference category that exists in account.

• “preference_name” – name of preference that exists in account and assigned to the category

• “operation” – operation that has to be applied on the contact preference value. It might be one of:

  • “equals”

  • “notequals”

  • “defined”

  • “undefined”

• “value” – this paremeter is mandatory only in case if “operation” is “equals” or “notequals” and must contains one of the Boolean values:

  • true

  • false

An example of JSON in request body to create contact filter based on Contact Preferences might look like this:

REST API

Creating a Contactfilter

POST https://api.maileon.com/1.0/contactfilters/v2

URL Parameters

Header Information

• Content-Type: application/json

• Accept: application/json

Body

• Contactfilter JSON

Response

Response Format

If everything is OK, the response contains the IDs of the created elements.

Updating a Contactfilter

PUT https://api.maileon.com/1.0/contactfilters/v2/contactfilter/{:contactFilterId}

Example: PUT https://api.maileon.com/1.0/contactfilters/v2/contactfilter/2773

Header Information

• Content-Type: application/json

• Accept: application/json

Body

• Contactfilter JSON

Response

Error Handling

In Case of errors, e.g. validation errors, an error message is returned:

In this case there is a validation error: the startset of rule 0 (the first rule) is obviously wrong and indeed “al” was submitted instead of “all”.

In this case a contact filter has been specified as selection base that does not exist in the account.

Further Examples

Create a filter based on a given domain

Create a filter based on a list of domains

Example collection

This archive contains a few contactfilter JSON files. Files starting with “valid“ mark valid examples, while files starting with “invalid” mark invalid examples that might still be useful for understanding usage.

Open

Changelog

15.03.2023, Version 1.0.0

• Ported final version to Confluence

13.08.2022, Version 0.8.0

• Added documentation and examples about contact field operations

• Added new possibility to add filters where contact field value is included in external resource (URL)

10.02.2022, Version 0.7.0

• Added documentation and examples about using contact preferences

20.07.2021, Version 0.6.0

• Added documentation and examples about using contact events / transactions in filters

17.11.2021, Version 0.5.1

• Added information about standard fields

• Added examples

09.07.2021, Version 0.5.0

• Added contect event description