Create Transactions

Creates any number of transactions in the account.

Required existence of contacts

Please be aware if you send a transaction and the provided contact does not exist, the transaction cannot be sent. Originally, the contact also needed to have a valid permission but since December 2019, it is possible to mark transaction mails, like order confirmation or billing mails, to require no permission, as no advertisement content is contained. The preferred way to deal with such cases is to synchronize the contacts with Maileon properly with the correct attributes and permissions. However, if there is any reasons for situations where you want to send transaction mails to contacts that might not exist, you can wrap the contact in an import statement (see table) and provide a permission that should be assigned to the contact, if it did not exist. This fallback solution will only create a contact with an email (and optionally an external id). To keep the data stream small, fast, and efficient, no further contact details are submitted. If you need to submit more data, you need to properly create the contact first.

For information on valid values for different data types, e.g. date(time), see https://support.maileon.com/support/create-transaction-type/

Request

POST https://api.maileon.com/1.0/transactions

Media type: application/json In order to ensure timely processing of your transactions, a size limit of 9M (9,000,000 bytes) for the request entity is enforced by the API. If you need to submit batches of transactions that are bigger than that, please split them up into individual requests.

Query parameters

Parameter	Default	Description
ignore_invalid_transactions	true	If set to false, exceptions like invalid contacts will cause the service to return 400 Bad request.
generate_transaction_id	false	If the transaction type contains the special attribute „transaction_id“, setting this method to true will generate and fill a random ID in this field and return the ID in the report. This can be used if the ID is not generated externally.

The body has the media type application/json and contains a list of transaction objects. A transaction object has the following attributes:

Attribute	Required	Description
type	yes***	the numeric ID of the transaction type to use. *** Since May 2020, “typeName” can be used instead. If “type” and “typeName” are set both, “type” will be used.
typeName	yes***	the name (string) of the transaction type to use. *** Since May 2020, “typeName” can be used as an identifier. If a transaction type is changed and the same name is used, this identifier can be used instead of the ID to avoid changes in external settings or code.
contact	yes*	* Either contact of import is required. If both are specified, only the “import” cantact is used. An object identifying the contact that contains at least one of the following attributes
contact.id	no	the Maileon ID of the contact to send the transaction to
contact.email	no	the email address of the contact to send the transaction to
contact.external_id	no	the external ID of the contact to send the transaction to
import.contact	yes	an object identifying the contact that contains at least one of the following attributes
import.contact.id	no	the Maileon ID of the contact to send the transaction to
import.contact.email	yes**	** required, to create not existing contacts. The email address of the contact to send the transaction to.
import.contact.external_id	no	the external ID of the contact to send the transaction to. This can be set in addition to the email, if the newly created contact should be registered with an email and the external ID.
import.contact.permission	yes	the permission that should be used when creating a new contact. Existing contacts will not be updated. If permission 1 (none) is used, Maileon can only send trigger mails that are set to „permission neutral sendout“, such as order confirmations. Shopping cart abandonnment mails for exmple usually require a valid advertisement permission and would not be sent as Maileon is not allowed to send advertisement mails to contacts with “none” as permission. Supported values are 1 to 6: 1: none, 2: single opt-in, 3: confirmed opt-in, 4: double opt-in, 5: double opt-in plus, 6: other
content	yes	an object that contains the transaction content as defined in the referenced transaction type
attachments	no	A list of attachments that will be sent to the receipient along with the transaction e-mail. Note that this is only guaranteed to work if the transaction results in a single mailing (i.e. there is exactly one trigger mailing defined for the transaction contact event). Executable files are not allowed.
attachments[i].filename	yes, if an attachment is submitted	the file name to use for the attachment in the generated transaction e-mail
attachments[i].mimetype	yes, if an attachment is submitted	the mime type to specify for the attachment as part of the generated transaction e-mail
attachments[i].data	yes, if an attachment is submitted	the binary contents of the attachment, encoded in Base64. The total amount of data per Transaction may not exceed 1MB (that is 1,000,000 bytes) when decoded to binary representation. Please note that the size of the entiry HTTP request entity may not exceed 9MB (9,000,000 bytes) in total.

The body might look like this:

[
    {
        "type": 20,
        "contact": {
            "external_id": "external-id-4"
        },
        "content": {
            "currency": "$",
            "shipping_address": {
                "line1": "512 Means St NW Ste",
                "line2": "404",
                "line3": "Suite 404",
                "line4": "Atlanta, Georgia 30318",
                "line5": "United States"
            },
            "billing_address": {
                "line1": "Atlanta, Georgia 30307",
                "line2": "United States"
            },
            "subtotal": 54.98,
            "shipping": 0,
            "tax": 0,
            "discount": 0,
            "total": 54.98,
            "item": [
                {
                    "title": "Striped Down Cardigan",
                    "url": "http://....",
                    "image": "http://...",
                    "details": "Size L",
                    "categories": [
                        "SizeL",
                        "Woman"
                    ],
                    "quantity": 1,
                    "price": 34.99
                },
                {
                    "title": "Three Little Birdies Wall Hook",
                    "url": "http://....",
                    "image": "http://...",
                    "details": "Color No Color",
                    "categories": [
                        "Furniture"
                    ],
                    "quantity": 1,
                    "price": 19.99
                }
            ]
        },
        "attachments": [
            {
                "filename": "you_invoice.pdf",
                "mimetype": "application/pdf",
                "data": "JVBERi0xLjMNJeLjz9MNC...
            }
        ]
    }
]

When using the import syntax to create not existing contacts: The body might look like this:

[
    {
        "type": 20,
        "import":{
            "contact":{
                "email":"max.mustermann@xqueue.de",
                "external_id": "external-id-4",
                "permission":2
        },
        "content": {
            ...
        }
    }
]

Response

HTTP status code	Description
200 OK	transactions were successfully queued, report is attached
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.
413 Request Entity Too Large	If the submitted entity was larger than 9M (9,000,000 bytes). If your request contained multiple transactions, you may be able to fix the problem by splitting it up into separate requests.

Media type: application/json The request returns a report that details if queuing was successful for each transaction. Note that if one of the transactions is invalid and ignore_invalid_transactions is false, a 400 Bad Request response will be generated instead.

Example response body

{
    "reports": [
        {
            "contact": {
                "id": 218,
                "external_id": "external-id-4"
            },
            "queued": "true"
        },
        {
            "contact": {
                "email": "unknown@xqueue.com"
            },
            "queued": "false",
            "message": "No valid contact identification provided for transaction."
        }
    ]
}

Example response body when transaction_id is specified

{
    "reports": [
        {
            "contact": {
                "id": 218,
                "external_id": "external-id-4"
            },
            "queued": "true",
            "transaction_id": "abc123"
        },
        {
            "contact": {
                "email": "unknown@xqueue.com"
            },
            "queued": "false",
            "transaction_id": "abc456",
            "message": "No valid contact identification provided for transaction."
        }
    ]
}

PHP Code Example – Full Walkthrough

The following code is based on the PHP Api Client. We will show you how to create an order confirmation mail from some imaginary webshop. The preassumption is, that you already have some experience with Maileon and that you know a little bit about PHP. If there are questions like “how can I add a transaction type” or even “and what is a transaction type??”, just drop an email to: service@xqueue.com. We focus on the PHP code and provide only basic information about the event type and the mailing itself. If you are going to test the code you need a Maileon account and you can ask your reseller or the XQueue customer support to import the event type and the sample mailing to your account: – Order confirmation event – Order confirmation mailing template (coming soon) The first step is to create a proper event type. We provide a generic type in the above package which contains some basic information (like the items, shipping/billing address, …) and some free values (generic_fields.string1-10, which you can freely set in your shop and print it in the mailing, e.g. if you want to provide different additional vouchers for the next shopping tour). The list of basic attributes (none is required, the custom attributes are skipped as there are 10 of each type like string, date, …):

	Attribute	Required	Format
order.id			Text
order.date			Zeitstempel
order.date_formatted			Text
order.items			JSON
order.subtotal			Gleitkommazahl
order.shipping_fee			Gleitkommazahl
order.tax_rate			Gleitkommazahl
order.tax_amount			Gleitkommazahl
order.credit			Gleitkommazahl
order.total			Text
order.currency			Text
order.url			JSON
order.attachments			Text
billing.fullname			Text
billing.address.line1			Text
billing.address.line2			Text
billing.address.line3			Text
billing.address.line4			Text
billing.address.line5			Text
billing.contact1			Text
billing.contact2			Text
billing.method.type			Text
billing.method.detail1			Text
billing.method.detail2			Text
billing.method.detail3			Text
billing.method.detail4			Text
billing.method.detail5			Text
billing.due_date			Zeitstempel
billing.due_date_formatted			Text
shipping.fullname			Text
shipping.address.line1			Text
shipping.address.line2			Text
shipping.address.line3			Text
shipping.address.line4			Text
shipping.address.line5			Text
shipping.contact1			Text
shipping.contact2			Text
shipping.method			Text
shipping.tracking_code			Text
shipping.tracking_url			Text
shipping.delivery_date.earliest			Zeitstempel
shipping.delivery_date.earliest_formatted			Text
shipping.delivery_date.latest			Zeitstempel
shipping.delivery_date.latest_formatted			Text
customer.salutation			Text
customer.full_name			Text
customer.id			Text

Now it’s about time to use the event type and fill the values. Go to the event type in Maileon and note the API ID of the type, e.g. 235. The following code will create an event of type 235, which is in our test account the order confirmation type from above.

// Create the configuration
$config = array( 
  	"BASE_URI" => "https://api.maileon.com/1.0",
    "API_KEY" => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // Your private API-Key

    "THROW_EXCEPTION" => "true",
    "DEBUG" => "true", // NEVER enable on production
    "TIMEOUT" => 0
);

// Create an instance of the transaction service that will be used to send transaction events to Maileon
$transactionsService = new com_maileon_api_transactions_TransactionsService($config);

// Create a transaction event and specify basic settings
$transaction = new com_maileon_api_transactions_Transaction();
$transaction->contact = new com_maileon_api_transactions_ContactReference();
$transaction->contact->email = $TESTDATA['transactionUserEmail'];
$transaction->type = $TESTDATA['transactionTypeId'];
$transaction->type = 235;

// Specify the content
$transaction->content['order.id'] = "76439965";
$transaction->content['customer.full_name'] = "Max Mustermann";
$transaction->content['order.currency'] = "€";

$transaction->content['order.date'] = "11.11.2015";
$transaction->content['order.total'] = 151.99;

$transaction->content['billing'] = array(
    "fullname" => "BillingMax BillingMustermann",
    "address.line1" => "BillingStreet Line 1",
    "address.line2" => "BillingStreet Line 2",
    "address.line3" => "BillingPLZ",
    "address.line4" => "BillingCity",
    "method.type" => "Credit Card");

$transaction->content['shipping'] = array(
    "fullname" => "ShippingMustermann",
    "address.line1" => "ShippingStreetLine1",
    "address.line2" => "ShippingStreetLine2",
    "address.line3" => "ShippingPLZ",
    "address.line4" => "ShippingCity");

// Here we got some complex data, which will be converted to JSON
$transaction->content['order.items'] = array(
    array(
        'title' => 'Ordered Item 1',
        'articlenumber' => "0000000000001",
        'imageUrl' => "http://www.xqueue.de/tl_files/layout/logo.png",
        'unitPrice' => "20",
        'amount' => "5",
        'packagingUnit' => "Pieces",
        'cummulativePrice' => "100",
        'discountSource' => "Volume Discount",
        'deliveryTime' => "3 Working Days"),
    array(
        'title' => 'Ordered Item 2',
        'articlenumber' => "0000000000002",
        'imageUrl' => "http://www.xqueue.de/tl_files/layout/logo.png",
        'unitPrice' => "10",
        'amount' => "5",
        'packagingUnit' => "Pieces",
        'cummulativePrice' => "50",
        'discountSource' => "",
        'deliveryTime' => "3 Werktage"),
    array(
        'title' => 'Ordered Item 3',
        'articlenumber' => "0000000000003",
        'imageUrl' => "http://www.xqueue.de/tl_files/layout/logo.png",
        'unitPrice' => "1,99",
        'amount' => "1",
        'packagingUnit' => "Pieces",
        'cummulativePrice' => "1,99",
        'discountSource' => "",
        'deliveryTime' => "3 Working Days"));

// Just one transaction, you could also send them as bulk messages
$transactions = array($transaction);

// Finally send the request. Here you should log or check the response.
$response = $transactionsService->createTransactions($transactions, true, false);

If you misspell something or you provide a wrong data type, the API will notify you about it, e.g.:

{"reports":[{"contact":{"id":196908,"email":"max.mustermann@xqueue.de"},"queued":false,"message":"The provided attribute 'order.total' cannot be transformed: double expected."}]}

In this case, I provided “151.99” instead of 151.99 (notice the “” around some value indicates a string). If the client is set to debug mode and everything runs fine, the output will be similar to this:

cURL session log

* Hostname api.maileon.com was found in DNS cache
*   Trying 212.6.132.213...
* Connected to api.maileon.com (212.6.132.213) port 443 (#0)
* successfully set certificate verify locations:
*   CAfile: C:\tools\cacert.pem
  CApath: none
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* Server certificate:
* 	 subject: OU=GT46929084; OU=See www.rapidssl.com/resources/cps (c)15; OU=Domain Control Validated - RapidSSL(R); CN=*.maileon.com
* 	 start date: 2015-05-14 00:59:55 GMT
* 	 expire date: 2018-05-15 20:16:29 GMT
* 	 subjectAltName: api.maileon.com matched
* 	 issuer: C=US; O=GeoTrust Inc.; CN=RapidSSL SHA256 CA - G3
* 	 SSL certificate verify ok.
> POST /1.0/transactions?release=true&ignore_invalid_events=false HTTP/1.1
Host: api.maileon.com
Content-type: application/json
Accept: application/json
Authorization: ***redacted***
Content-Length: 1448

* upload completely sent off: 1448 out of 1448 bytes
< HTTP/1.1 200 OK
< Server: nginx/1.4.6 (Ubuntu)
< Date: Thu, 26 Nov 2015 08:44:54 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Connection: keep-alive
< 
* Connection #0 to host api.maileon.com left intact

Result

status code: 200 OK
is success: true
is client error: false

body data:
{"reports":[{"contact":{"id":196908,"email":"max.mustermann@xqueue.com"},"queued":true}]}

Result type: stdClass

success (Status code: 200 – OK) In the maileon UI, you can now see the incoming transaction: event, it will now be sent to the given email address. If you have a trigger mailing active that listenes for the

Running examples (with code download)

Simple Transaction Create a single transaction event providing your API-Key, a transaction type ID and an email to send the (empty) transaction to. This example expects, that you have created a transaction type inside Maileon with no mandatory attributes. Complex Transaction (Order Confirmation) Create a single transaction event providing your API-Key, a transaction type ID and an email to send the (empty) transaction to. This example can also create the required transaction type for our (minimized) sample order event, if required. https://hosting.maileon.com/service/examples/en/transaction_tutorial/index.php