Creates a new transaction type with the given name in the account.

Request

Media type: application/vnd.maileon.api+xml or application/json
This method can be called with either XML of media type application/vnd.maileon.api+xml or with JSON of media type application/json. Both variants of the method differ slightly in how a definition of the transaction type attributes is arrived at. Generally, the XML request offers more options for configuring transaction attributes.

XML specification

A transaction type definition contains a set of basic settings for the transaction type and a set of attributes which will contain the data later on. The following table defines the attributes for the transaction type itself:

Attribute Required Default Description
name yes The name of the transaction type. The name must start with a alphabetic character and may contain alphanumerical characters as well as „_“ but no space. A name can be hierarchical, i.e. the different levels can be separated by a „.“, for example: „product.image.url“. The names between the „.“, i.e. the names on the different levels, may be up to 32 characters and the overall name may be up to 255 characters long.
description no If set, this value will be submitted as description for the transaction type. The length is limited to 1000 characters.
archivingDuration no not set (=infinite) If set, this parameter specifies the number in days a transaction event will be saved in Maileon before being deleted. Please be aware that evaluations on transaction events are not possible after they have been deleted and for mailings containing content from the transaction events, rescue links will not render properly after deleting the events.
storeOnly no false If nothing or false is specified, the limit for strings attributes of the transaction is set to 1000 characters and the transaction event can be used in any contactfilter, e.g. „give me all contacts that received contact event X with value Y in attribute Z“.
If storeOnly is set to true, the attributes of the transaction cannot be used as comparision inputs for contactfilters but the allowed length is raised to 64.000 characters.
attributes yes The list of attributes of the transaction type. The list may be empty.

Any number of attributes can be specified. The following table explains the child elements of <attribute>:

Attribute Required Default Description
name yes The path of the JSON element that contains the attribute value. A dot (“.”) is used as path separator. In the above example, the transaction content of an actual transaction might look like this:

In this case, the firstname attribute would have to be called customer.firstname. Attribute paths may be up to 255 characters long.

Note: the name itself is limited to 255 characters.

description no If set, this value will be submitted as description for the attribute. The length is limited to 1000 characters.
type yes Defines the type of the attribute. Valid types are string (maximum length 1000 characters), double, float, integer, boolean, timestamp and json. A valid timestamp is a UNIX epoch timestamp represented as a long integer or a string that contains an iso-formatted date (e.g "2014-02-08" or "2014-02-08 14:34:20"). json is a free-form JSON list element („[...]„) that contains arbitrary JSON data and is up to 64000 bytes long.
required no false If this is set to true, any transactions that do not contain this attribute will be rejected by the method Create Transactions.

Defining a transaction type using a JSON data example

An easier, if less flexible way of defining a transaction type is by submitting a JSON body of the following form:

In this form of the method, an example of the JSON that would be submitted to Create Transactions is provided in the content attribute of the JSON request body. The system will then extract attribute definitions from the example transaction content according to the following rules:

  • all elements are converted to attributes with a name that corresponds to their path in the JSON syntax tree
  • the type of the attributes is defined as follows:
    • Strings are mapped to string
    • Floating-point numbers are mapped to double
    • Natural numbers are mapped to integer
    • Booleans are mapped to boolean
    • Lists are mapped to json
  • all attributes are created as optional (i.e. with required=false)

Note that it is impossible to create mandatory attributes, as well as attributes of type float or timestamp using this technique. Since it is impossible to change a transaction type once it is defined, we recommend using the XML body format instead if you need any of these features.

Response

HTTP status code Body Content Description
200 Ok / <transaction_type_id>258</transaction_type_id> transaction type successfully created
400 Bad Request If there was an error in the submitted body. In this case, an XML-form error message that explains the problem is produced.

Special Attributes

There is a special attribute called „transaction_id“. The attribute has to be specified like every other text attribute when creating the transaction type. This attribute is always limited to 1000 characters, ignoring the storeOnly setting. If a transaction is sent to Maileon and the „transaction_id“ attribute is set, this value can be returned using the Maileon webhooks. So, if you e.g. register a webhook for bounces, your system will be notified with the exact id that was specified in the transaction, so it should be unique for each call. Also a header „X-Transaction“ will be added to the mailings, so manual replies can also be assigned to a specific mail.