+49 69 83008980 service@xqueue.com
Benötigen Sie Hilfe?

Im Maileon Help-Center finden Sie umfassende Dokumentationen zu unserem System.

Beliebte Suchanfragen: Importe | Rest-API | Integrationen | SMS

Create Transactions

Sie sind hier:

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

Inhaltsverzeichnis