Maileon - Transactions - An Interactive Walkthrough

Introduction

Welcome to the interactive transaction tutorial.
This tutorial is for technical and non technical people who want to get an understanding how transaction mails, like order confirmations or invoices, work. It will guide you through all steps and explains all components that are required to get data from your system into a trigger mailing that is instantly sent by Maileon. This includes questions like "Where do I get an API key?", "What is a transaction type?" or "How do I decide which mail to trigger?".

The tutorial is realized as a workflow that requires to execute the steps in a given order, e.g. as an API key is mandatory, you cannot start with the second step without providing a valid API key in the first step.

The tutorial will use the information sign to hide details in order to avoid overloading the regular text with too much information. If more information is available, the following icon will appear and you can click on it:

API Credentials

In order to submit a transaction to Maileon, you first need a valid API-Key. A valid API-Key has the form XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, click here for more information about API keys:

If you enter an API key in the field below, you agree, that this key is used for the purpose of demonstrating how to handle transaction types, including creation of transaction types and triggering transactions to emails specified by you in the last step.

Api-Key:

Transaction Type

To submit transactional data to Maileon, you need to have a valid "transaction type". A transaction type is the data model describing all attributes of the data you wish to submit, e.g. if you are planning to submit an order confirmation, the transaction type will contain an attribute for the list of items, one for the overall price, maybe some attributes describing the shipping address, etc. This information is required for two purposes:

When you create a trigger mailing that should be sent after receiving your transaction, Maileon needs to know which attributes are available, so the designer of the mail can insert the correct attribute names.
You can set attributes to be mandatory or optional. When submitting transactions via API, Maileon will check if all mandatory attributes are filled properly.

In this step, this script will check, if a suitable transaction type is already registered in your account. If it is found, you will see its ID below, if not, you will be asked to let the script create the type for you.

There are two ways of creating a transaction type:

Using the UI (select 'Lists & Contacts' and then 'Contact Events')
Using the API

. In order to demonstrate the process, this script can create a transaction type using the API if you click the button below.

• For more information about transaction types, click here:
• For more information about the PHP code that can create a transaction type, click here:



use de\xqueue\maileon\api\client\HTTPResponseCodes;
use de\xqueue\maileon\api\client\transactions\TransactionsService;
use de\xqueue\maileon\api\client\transactions\AttributeType;
use de\xqueue\maileon\api\client\transactions\TransactionType;
use de\xqueue\maileon\api\client\transactions\DataType;

// Create the configuration holding the API key
$config = array(
	"BASE_URI" => "https://api.maileon.com/1.0",
	"API_KEY" => "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
	"DEBUG" => false
);

// Create the service
$transactionsService = new TransactionsService($config);

// Define the attributes of the transaction type
$attributes = array();
array_push($attributes, new AttributeType(null, "gender", DataType::$STRING, false));
array_push($attributes, new AttributeType(null, "title", DataType::$STRING, false));
array_push($attributes, new AttributeType(null, "first_name", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "last_name", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "phone", DataType::$STRING, false));
array_push($attributes, new AttributeType(null, "campaign", DataType::$STRING, false));
array_push($attributes, new AttributeType(null, "webshop_id", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "language", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "customer_no", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "order_no", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "currency", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "billing_address.name", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "billing_address.street1", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "billing_address.street2", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "billing_address.zip", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "billing_address.city", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "shipping_address.name", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "shipping_address.street1", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "shipping_address.street2", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "shipping_address.zip", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "shipping_address.city", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "items", DataType::$JSON, true));
array_push($attributes, new AttributeType(null, "order_date", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "total", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "payment_type", DataType::$STRING, true));
array_push($attributes, new AttributeType(null, "voucher_code", DataType::$STRING, false));

// And create a transaction type with name "order_confirmation_standard"
$trt = new TransactionType(null, "order_confirmation_standard", $attributes);

            
// Submit it to Maileon
$response = $transactionsService->createTransactionType($trt);

// Check the response
if ($response->isSuccess()) {
	...
} else {
	...
}

Transaction Data

In this step, you will send transactional data in the form of an order confirmation event to Maileon. Remember, the data attributes have only been chosen for this example is not fixed and you can specify the attributes as you need them. An order confirmation does not need to contain the exact attributes shown in this example.

Additional information:

Transactional data itself will be collected in Maileon but, by default, it does not trigger a mail. If you are interested in triggering a mail, e.g. a mail listing the ordered items, you will need to create a "trigger mailing", see here for details:
For more information about the PHP code that can create a transaction, click here:

Email:

If the contact does not exist, this code will automatically create an empty contact, filled with the email, only. If not existing before, the permission will be set to NONE as this is not a newsletter subscriber.
If you need more data being set to the contact object permanently, please use the apropriate methods for creating a contact, first.
If you want to send transaction mails, like order confirmations or invoices, also to contacts without permission, make sure to set the "permission neutral" option in the last step (dispatch options) of the mailing setup.

Hint: the transaction event itself will be recorded in any case.

Firstname:

Lastname:

If you want a sample order confirmation mail to be triggered, you need to:

Create a "trigger mailing".
In the mailing content you need to use placeholders (so called Mergetags) for defining where to print data from the transaction. This also includes loops e.g. for listing all the purchased products.
When finished, you need to select in the last workflow step ("Dispatch logic & approval") as "Mailing Logic" the option "Single dispatch for an event", then select your transaction type, e.g. in this example "order_confirmation_standard", see the screenshot:
Once the mail is active, it will be triggered every time when transaction data of the specified type is submitted over the Maileon API.

For an easier start with creating such a mailing, we provide a sample mail including a loop over the items that we submit in this example. To use the template, you need to follow these steps:

Download the template here.
If you have partner status, you can upload the template yourself, otherwise ask our customer service to upload it for you: service@xqueue.com
As a partner, log into the account, go to "Media & Templates", then "Templates - Mailing Templates". Then click on the upload button shown in the following screenshot:
When finished, the mailing is currently named "475", please rename it, e.g. "Order Confirmation".
Once the template is uploaded, you can select it when creating the trigger mail. If done so, the mailing will look like:

For the sake of demonstration, this template uses a RAW-HTML-Article for the purchased items. In the sourcecode below, you can see the loop defining the products to be found in attribute called "items" (must be defined in the transaction type as JSON), the item will simply be called i inside the loop. You can of course also use a WYSIWYG-Article, just wrap the loop definition around the article and print the attributes of each loop item. The attributes inside the loop element are then just printed by using a mergetag like: [[ITEM|i|single_price|]]


								
<!-- [[LIST|TRANSACTION|items|i]] -->
<table cellpadding="0" cellspacing="0" border="0" width="100%">
  <tr>
    <td align="left" valign="middle" width="3%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
    <td align="center" valign="middle" width="14%" height="56"><img src="[[ITEM|i|thumbnail|]]" title="[[ITEM|i|short_description|]]" style="display:block;" border="0" /></td>
    <td align="left" valign="middle" width="1%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
    <td align="left" valign="middle" width="44%" height="50">
      <table cellpadding="0" cellspacing="0" border="0" width="100%">
        <tr>
          <td align="left" valign="middle" width="100%" height="20"><b>[[ITEM|i|name|]]</b></td>
        </tr>
        <tr>
          <td align="left" valign="middle" width="100%" height="30">[[ITEM|i|short_description|]]</td>
        </tr>
      </table>      
      
    </td>
    <td align="left" valign="middle" width="1%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
    <td align="right" valign="middle" width="3%" height="50">[[ITEM|i|quantity|]]</td>
    <td align="left" valign="middle" width="1%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
    <td align="right" valign="middle" width="15%" height="50">[[ITEM|i|single_price|]] €</td>
    <td align="left" valign="middle" width="1%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
    <td align="right" valign="middle" width="15%" height="50">[[ITEM|i|combined_price|]] €</td>
    <td align="left" valign="middle" width="3%" style="line-height:1px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="1" border="0" style="display:block;"/></td>
  </tr>
  <tr><td colspan="10" align="left" valign="middle" height="15" style="line-height:15px;font-size:1px;"><img src="/u/ext/image/s.gif" width="1" height="15" border="0" style="display:block;"/></td></tr>
</table>
<!-- [[/LIST]] -->

Once the mailing is active, you will receive a mailing like this one when submitting a transaction:


use de\xqueue\maileon\api\client\HTTPResponseCodes;
use de\xqueue\maileon\api\client\transactions\TransactionsService;
use de\xqueue\maileon\api\client\transactions\Transaction;			
use de\xqueue\maileon\api\client\transactions\ImportReference;
use de\xqueue\maileon\api\client\transactions\ImportContactReference;
use de\xqueue\maileon\api\client\contacts\Permission;
    
// Create the configuration holding the API key
$config = array(
	"BASE_URI" => "https://api.maileon.com/1.0",
	"API_KEY" => "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
	"DEBUG" => false
);

// Just get the transaction ID from some database etc.
$txId = 5;

// Create the service
$transactionsService = new TransactionsService($config);

// Create the transaction object
$transaction = new Transaction();
				
// If you are sure the contact exists, e.g. because you created it beforehand, you can use this code to identify it
// $transaction->contact = new ContactReference();
// $transaction->contact->email = $email;

// However, in this example, we let Maileon create the contact, if it does not exist.
$transaction->import = new ImportReference();
$transaction->import->contact = new ImportContactReference();
$transaction->import->contact->email = $email;
$transaction->import->contact->permission = Permission::$NONE->getCode();

$transaction->type = $txId;

$transaction->content['first_name'] = "Max";
$transaction->content['last_name'] = "Mustermann";
$transaction->content['phone'] = "0815";
$transaction->content['webshop_id'] = "My Webshop ID";
$transaction->content['language'] = "de";
$transaction->content['campaign'] = "SALES Event 15";
$transaction->content['customer_no'] = "1234567890";
$transaction->content['order_no'] = "0987654321";
$transaction->content['currency'] = "€";

$transaction->content['billing_address'] = array(
        'name' => 'Max Mustermann',
        'street1' => "BillingStreet Line 1",
        'street2' => "BillingStreet Line 2",
        'zip' => "BillingPLZ",
        'city' => "BillingCity"
    );
$transaction->content['shipping_address'] = array(
        'name' => 'ShippingMax ShippingMustermann',
        'street1' => "ShippingStreet Line 1",
        'street2' => "ShippingStreet Line 2",
        'zip' => "ShippingPLZ",
        'city' => "ShippingCity"
    );

$transaction->content['items'] = array(
    array(
        'title' => 'Zartbitter mit Minze',
        'articlenumber' => "SW10119",
        'thumbnail' => "http://dev-shop1000.maileon.com/shopware/media/image/thumbnail/SW10119_100x100.jpg",
        'short_description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.",
        'description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo.",
        'single_price' => "3",
        'combined_price' => "18",
        'quantity' => "6",
        'packagingUnit' => "Stück",
        'deliveryTime' => "3 Working Days"),
    array(
        'title' => 'Worldcup Race Flex S Junior',
        'articlenumber' => "SW10012",
        'thumbnail' => "http://dev-shop1000.maileon.com/shopware/media/image/thumbnail/SW10012_100x100.jpg",
        'short_description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.",
        'description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo.",
        'single_price' => "119,95",
        'combined_price' => "119,95",
        'quantity' => "1",
        'packagingUnit' => "Stück",
        'deliveryTime' => "3 Working Days"),
    array(
        'title' => 'CROSS RIDER 18 WOMAN',
        'articlenumber' => "SW10142",
        'thumbnail' => "http://dev-shop1000.maileon.com/shopware/media/image/thumbnail/SW10142_100x100.jpg",
        'short_description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.",
        'description' => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo.",
        'single_price' => "89,95",
        'combined_price' => "89,95",
        'quantity' => "1",
        'packagingUnit' => "Stück",
        'deliveryTime' => "3 Working Days"));

$transaction->content['order_date'] = "11.09.2016";
$transaction->content['total'] = "227,90";
$transaction->content['payment_type'] = "Credit Card";

// Just sample output of the JSON string
$dataSent = json_encode( array($transaction));

// Only one transaction, here we could also submit some more transactions in one array
$transactions = array($transaction);

$response = $transactionsService->createTransactions($transactions, true, false);
	
// Check the response	
if ($response->isSuccess() && strpos($response->getBodyData(), '"queued":true') !== false) {
	// Remember: a transaction can be denied, you can set up the call to fail, in this case a report will be returned with the attribute "queued" set to false!
} else {
	
}

Complete

You have successfully completed all steps and if you created a trigger mailing, the mail should now be delivered as shown in the next screenshot:

If you are interested in more information about the process and how to check the result, see the following explanations:

In your Maileon account, you can check if a transaction event is received, for more information, see:
The JSON data that has been sent to Maileon can be viewed inside Maileon, see:
You can also check if a mail has been sent, see: