+49 69 83008980 service@xqueue.com

Benötigen Sie Hilfe?

Create Transactions

Sie sind hier:
< Alle Themen
 

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 needto submit more data, you need to properly create the contact first.

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.
 

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 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). 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

{
    "report": [
        {
            "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."
        }
    ]
}

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.
&gt; POST /1.0/transactions?release=true&amp;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
&lt; HTTP/1.1 200 OK
&lt; Server: nginx/1.4.6 (Ubuntu)
&lt; Date: Thu, 26 Nov 2015 08:44:54 GMT
&lt; Content-Type: application/json
&lt; Transfer-Encoding: chunked
&lt; Connection: keep-alive
&lt; 
* 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: 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

Inhaltsverzeichnis