Configuring transactional mails via HTTP API
Note
This topic is for administrators and developers with administration access rights in Magento 2.
This topic describes how to configure sending of transactional mails via HTTP API with Magento 2. For transactional mails via the SMTP API, see Transactional mails via SMTP API.
How it works
Sending of transactional mails via HTTP API uses these templates:
- A Sender template in Magento 2, which sends the variables of the transaction (for example customer name, ordered products) via the HTTP API.
- A Recipient template in Optimizely Campaign, which uses field functions to insert sent variables into relevant locations. This creates the finished transactional mail with layout.
Sending and receiving the content of the variables takes place using the transaction recipient list as a buffer.
- The Magento 2 template sends the variables.
- The variables are written to the transaction recipient list: each variable into the relevant recipient list field.
- Using field functions, Optimizely Campaign copies the template with the individual variables from the transaction recipient list and places it in the desired location in the transactional mail.
Configuration steps
- Set up a transaction recipient list.
- Create the template in Optimizely Campaign.
- Create and activate the template in Magento 2.
configuring-transactional-mails-via-http-api.mdxStep 1. Setting up a transaction recipient list
To set up the transaction recipient list. contact customer support. Plan in advance which variables you want to transfer from Magento 2 into Optimizely Campaign for your transactional mails.
List the Magento 2 variables for which you require a corresponding recipient list field in your transaction recipient list. Also, let Optimizely know the naming of the recipient list fields.
Note
The scope of the transaction recipient list is limited. For this reason, you should request generic names for the recipient list fields, for example custom_string_1, custom_string_2, custom_date_1 and so on.
configuring-transactional-mails-via-http-api.mdxStep 2. Creating a template in Optimizely Campaign
Create the template and add the desired transactional mail texts (the unchangeable, static texts that are to be sent to recipients) and insert field functions in the places where the content of the Magento 2 variables should be.
Field functions
Field functions are placeholders that refer to a specific recipient list field in your transaction recipient list. The variables and content of the variables sent from Magento 2 are written into the relevant recipient list fields in your transaction recipient list. The field functions you place load relevant content from the referenced recipient list field in the next step.
Set up a transactional mail text that greets each customer using the last name and the order date. For this you need these variables: salutation, lastname and orderdate.
The content of the variables is first written to a relevant recipient list field of the transaction recipient list (from Magento 2 via the HTTP API). To access these recipient list fields, insert the individual field functions into the Optimizely Campaign template and place the name of the recipient list field in curly brackets. To import the variable contents, the static text and field functions in the Optimizely Campaign template could look like this:
Hello, {salutation} {lastname}! Thank you for your online order from {orderdate}.The example will appear in the sent transactional mail as follows:
Hello, Mr. Miller! Thank you for your online order from August 3.
Adding static texts and field functions to a template
- Open the Optimizely Campaign menu and select Campaigns > Transactional Mails.
- Click Create.
- From the left action pane, drag the Recipients node into the workspace.
- In the Recipient lists drop-down list in the context menu, select your transaction recipient list.
Note
Customer support has set up a separate transaction recipient list for you. Make sure you use this transaction recipient list, instead of a regular recipient list. To see if a recipient list is a transactional recipient list, check the column Transaction API.
- From the left sidebar, drag the message node for the desired marketing channel (email, SMS) into the workspace.
- In the Name box in the context menu, enter a name for your transactional mail (for example Order confirmation).
- In the context menu for the message node, click Edit content.
- In the Template list, select the desired template and confirm your selection by clicking Next.
- Configure the template for the transactional mail according to your requirements. Enter a subject and insert the static texts that recipients will receive, into the content paragraphs. Insert the relevant field function for the recipient list field of the transaction recipient list into places where variables from the Magento 2 template should appear (see example above).
- Click Apply.
- Click Close.
- Connect the Recipients node with the message node.
- Click Save and Close.
- Select the mailing in the overview and click Start to activate your transactional mail and to start the sending process.
configuring-transactional-mails-via-http-api.mdxStep 3. Creating and activating the template in Magento 2
Create a template in Magento 2 that sends the variables to Optimizely Campaign via HTTP API.
Prerequisites
- Authorization code. For your transaction recipient list in to Optimizely Campaign. Open the Optimizely Campaign menu and select Administration > API Overview > Recipient lists tab and select the desired transaction recipient list. Click Manage authorization codes and copy the authorization code from the list. If no authorization code is available for the selected recipient list, click Create authorization code.
- Mailing ID. For the template in Optimizely Campaign. Open the Optimizely Campaign menu and select Campaigns > Transactional Mails. Copy the relevant mailing ID of the template in the list in column ID.
Configuration options
With Magento 2, you have two template configuration options for transferring variables:
- Use a template included in the standard Magento 2 installation and customize it to fit your needs. If you choose this option, the template's HTML code loads in the template content field. The code contains the available variables, for example {{trans "%name," name=$customer.name}} (for addressing customers by their names). Clean up the template around the HTML code and reduce the template to the variables. In the next step, map the corresponding recipient list fields of your transaction recipient list in Optimizely Campaign. See Mapping: Here’s how you do it.
- Create an empty template and manually insert the variables to be sent to Optimizely Campaign via the HTTP API.
Do the following to create a template, add the variables and map these to the recipient list fields of your transaction recipient list.
- Log in to Magento 2 with administrator rights.
- Select Marketing > Email Templates.
Note
If you already created templates that are sent to Optimizely Campaign, these appear as the template type Episerver.
- Click Add New Template.
- In the Template Information area, fill in the fields:
- Template Name. Enter a name for the new template.
- Template Subject. Leave empty.
Note
The subject is automatically entered later using the subject from the template created in Optimizely Campaign.
- Episerver Campaign. Select Enabled.
- Authcorisation Code. Enter the authorization code for the transaction recipient list in Optimizely Campaign.
- bmMailingId. Enter the mailing ID of the template in Optimizely Campaign.
- In the Template Information box, enter which variables from Magento 2 should be transferred to which recipient list field of the transaction recipient list in Optimizely Campaign. To add a variable, click Insert Variable...
- Select the desired variable by clicking it.
- Map the inserted variable with the corresponding recipient list field in Optimizely Campaign. If required, click Insert Variable... to add further variables. configuring-transactional-mails-via-http-api.mdxHow to do the mapping Magento 2 integration from Optimizely Campaign uses the following structure for mapping:
Name of the recipient list=name of the Magento 2 variablesEnter the mapping assignment for each variable line by line, and separate the individual variables/mapping instructions with a line break. Example:
lastname={{config path="trans_email/ident_custom1/name"}}
url={{config path="web/secure/base_url"}}Map with both example lines and transfer:
- Value of the Magento 2 variables {{config path="trans_email/ident_custom1/name"}} into the transaction recipient list field lastname
- Value of the Magento 2 variables {{config path="web/secure/base_url"}} into the transaction recipient list field url
- Click Save Template.
- After you create the template, activate it and map an event (for example an order process, or newsletter registration). At which point in the admin interface you map and activate the template to an event depends on the type of the event. Example: To map and activate the template to the event type Order, do the following:
- Select Stores > Configuration.
- Select Sales > Sales Emails.
- Activate the template by selecting it in the Order area in the New Order Confirmation Template drop-down list.
- Save your changes.
configuring-transactional-mails-via-http-api.mdxStep 4. Configuring transactional mails and transferring Magento 2 variables
To transfer customer orders and billing and delivery addresses to the template in Optimizely Campaign, using the template in Magento 2, you need additional configuration, and create a special field function (for order access) in your Optimizely Campaign client.
Note
Magento 2 provides the customer orders and billing and delivery addresses as HTML code. This needs to be changed to simple text so that Optimizely Campaign can process the information.
Converting HTML code to simple text
The following functions in the Magento 2 integration are for converting the HTML code into simple text:
getEpiserverBillingData( )
With getEpiserverBillingData( ), you get access to the individual parameters of the billing address. This feature is available via the following instruction, used in an example for the salutation of the customer:
{{var order.getEpiserverBillingData('salutation')}}You transfer the return value of the function call (parameter salutation) into the recipient list field salutation as simple text with the following mapping:
salutation={{var order.getEpiserverBillingData('salutation')}}getEpiserverBillingData( ) parameters
No. | Parameter | Description |
|---|---|---|
1 | salutation | Title |
2 | firstname | First name |
3 | middlename | Middle name |
4 | lastname | Last name |
5 | company | Company |
6 | Email address | |
7 | telephone | Telephone number |
8 | suffix | Extension |
9 | fax | Fax number |
10 | street | Street |
11 | postcode | Postal code |
12 | city | City |
13 | region | Region/state |
14 | country | Country |
getEpiserverShippingData()
With getEpiserverShippingData( ), you receive access to the individual parameters of the customer's delivery address. The feature is available via the following mapping, in this example for the customer's last name:
{{var order.getEpiserverShippingData('lastname')}}You transfer the return value of the function call (parameter lastname) into the recipient list field lastname as simple text with the following mapping:
lastname={{var order.getEpiserverShippingData('lastname')}}getEpiserverShippingData() parameters
No. | Parameter | Description |
|---|---|---|
1 | salutation | Title |
2 | firstname | First name |
3 | middlename | Middle name |
4 | lastname | Last name |
5 | company | Company |
6 | Email address | |
7 | telephone | Telephone number |
8 | suffix | Extension |
9 | fax | Fax number |
10 | street | Street |
11 | postcode | Postal code |
12 | city | City |
13 | region | Region/state |
14 | country | Country |
getEpiserverOrderData()
With getEpiserverOrderData( ), you access the customer's orders.
Note
Accessing orders differs from accessing the billing and the delivery addresses, as you transfer a list with several parameters into a single recipient list field, instead of transferring individual parameters.
The function is available via the following instruction (in this example, product ID, storage unit, product name, quantity ordered and price):
{{var order.getEpiserverOrderData('product_id','sku','name','qty_ordered','price')}}You transfer a string with the order information specified in the order_positions_csv into the recipient list field with the following mapping:
order_positions_csv={{var order.getEpiserverOrderData('product_id','sku','name','qty_ordered','price')}}getEpiserverOrderData( ) parameters
No. | Parameter |
|---|---|
1 | increment_id |
2 | state |
3 | status |
4 | coupon_code |
5 | shipping_description |
6 | is_virtual |
7 | store_id |
8 | base_discount_amount |
9 | base_discount_canceled |
10 | base_discount_invoiced |
11 | base_discount_refunded |
12 | base_grand_total |
13 | base_shipping_amount |
14 | base_shipping_canceled |
15 | base_shipping_invoiced |
16 | base_shipping_refunded |
17 | base_shipping_tax_amount |
18 | base_shipping_tax_refunded |
19 | base_subtotal |
20 | base_subtotal_canceled |
21 | base_subtotal_invoiced |
22 | base_subtotal_refunded |
23 | base_tax_amount |
24 | base_tax_canceled |
25 | base_tax_invoiced |
26 | base_tax_refunded |
27 | base_to_global_rate |
28 | base_to_order_rate |
29 | base_total_canceled |
30 | base_total_invoiced |
31 | base_total_invoiced_cost |
32 | base_total_offline_refunded |
33 | base_total_online_refunded |
34 | base_total_paid |
35 | base_total_qty_ordered |
36 | base_total_refunded |
37 | discount_amount |
38 | discount_canceled |
39 | discount_invoiced |
40 | discount_refunded |
41 | grand_total |
42 | shipping_amount |
43 | shipping_canceled |
44 | shipping_invoiced |
45 | shipping_refunded |
46 | shipping_tax_amount |
47 | shipping_tax_refunded |
48 | store_to_base_rate |
49 | store_to_order_rate |
50 | subtotal |
51 | subtotal_canceled |
52 | subtotal_invoiced |
53 | subtotal_refunded |
54 | tax_amount |
55 | tax_canceled |
56 | tax_invoiced |
57 | tax_refunded |
58 | total_canceled |
59 | total_invoiced |
60 | total_offline_refunded |
61 | total_online_refunded |
62 | total_paid |
63 | total_qty_ordered |
64 | total_refunded |
65 | base_shipping_discount_amount |
66 | base_subtotal_incl_tax |
67 | base_total_due |
68 | shipping_discount_amount |
69 | subtotal_incl_tax |
70 | total_due |
71 | base_currency_code |
72 | discount_description |
73 | global_currency_code |
74 | order_currency_code |
75 | shipping_method |
76 | store_currency_code |
77 | store_name |
78 | customer_note |
79 | created_at |
80 | updated_at |
81 | total_item_count |
82 | shipping_incl_tax |
83 | base_shipping_incl_tax |
84 | coupon_rule_name |
After the transfer to Optimizely Campaign, the individual parameters in the recipient list field of your transaction recipient list are separated by a semicolon. If multiple products are transferred, the individual products are separated by a line break. The string written in the recipient list field corresponds to the structure of a table that is saved in the CSV format.
configuring-transactional-mails-via-http-api.mdxCreating a special field function for order data
If you want to use order data in a transactional mail, you must create a new special field function in your Optimizely Campaign client. This must use the template engine of Optimizely Campaign to transfer the string to HTML, as described in the following.
- Open the Optimizely Campaign menu and select Administration > Field Functions.
Tip
If the Field functions menu item is not available in your client, contact customer support.
- Click Add.
- Under General, in the Name box, add a concise name for the new field function, for example CSVOrderObjects.
- In the Type drop-down list, select Velocity.
- In the Content area > Default replacement tab > Default replacement box, enter the following code:
<table><tr> <td>Product ID</td><td>SKU</td><td>Name</td><td>Quantity</td> <td>Price</td></tr>#set ("csvContent = "csv.readFromString("user.data.order_positions_csv))#foreach("row in "csvContent)<tr>
#foreach("item in "row) <td> "item </td>
#end</tr>#end</table>
- Click Save. Insert the field function at the desired location in the Optimizely Campaign template. When the transactional mail is sent and the recipient list field order_positions_csv contains a CSV context object, a simple HTML table is displayed in the sent transactional mail.
Note
See Field functions how to customize the layout of the table as desired (HTML knowledge is required).