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. The reason for this behavior is the strict interpretation of Maileon regarding contact permissions. If no permission exists, Maileon will never send an email to that contact.
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 needto submit more data, you need to properly create the contact first.

Request

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.

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
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 the contact. Do not use permission 1 (none) here as Maileon is not allowed to send any mail 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).
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:

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

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

 

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:

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 Gleitkommazahl
order.currency Text
order.url Text
order.attachments JSON
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.:

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

Result

success (Status code: 200 – OK)

 

In the maileon UI, you can now see the incoming transaction:

php_ce1

 

Detailview:

php_ce2

 

 

 

 

 

 

 

If you have a trigger mailing active that listenes for the event, it will now be sent to the given email address.

 

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