Overview
The Transactional API is used to trigger instant email messages to recipients.
General considerations
Ometria's rate limit for sending transactional emails is 10 requests per second.
The API ignores suppression lists for transactional sends, ensuring that contacts receive transactional emails regardless of status.
A typical implementation would involve a queue based system making calls to the Ometria API whilst being aware of the above constraints.
It is possible to set up a different sending domain or subdomain to provide differentiation between marketing and transactional emails. For example you could use service.yourdomain.com as the sending domain for your transactional emails.
Template options
With Transactional emails you have two options for your templates.
The transactional templates can be hosted in Ometria. When doing this you’ll pass the template ID and all the fields to merge in the API call. In this case, all the template assets, such as images can be hosted by the Ometria asset manager. In this case, it is potentially easier to make creative changes to your templates without the requirement of your development team.
The second option is to pass the HTML template within the transactional API call. The full HTML with all the data merged into it will need to be included in the API call.
Transactional Email Methods
Transactional Email objects
Transactional Email Address object
Transactional Email Content object
Transactional Examples
Transactional Email HTML Examples
Send Transactional Email
Path
POST /transactional-email/send
Description
Send a transactional email.
Request Body
|
Transactional Email object |
Request Example
{
"data": {
},
"from": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"profile_id": "",
"reply_to": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"sandbox": true,
"stream": "87tgHafe",
"subject": "Email Subject",
"template_id": 3,
"to": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"transactional": true
}
TransactionalEmail: object
Describes a Transactional Email record.
subject: string
The subject to be used in the email. 1024 character limit.
from: TransactionalEmailAddress
reply_to: TransactionalEmailAddress
transactional: boolean
Whether this email should be considered transactional or not. If you wish to check that the recipient is subscribed, set transactional to false.
stream: string default
A string that can be made up for tracking purposes.
profile_id: string
Accepts a profile ID and this will make profile information available as dynamic content to be loaded into the email.
template_id: integer
The ID of the HTML email template to be used.
content: TransactionalEmailContent
data: object {}
Data passed in this object will be made available as dynamic content, available to be merged into the template before sending.
sandbox: boolean
When set to true, the email will be processed but not sent. To be used during testing.
url_parameters: string
The URL parameters to be appended for this campaign.
Note: These parameters can be set as default in the Ometria interface.
Example
{
"data": {
},
"from": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"profile_id": "",
"reply_to": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"sandbox": true,
"stream": "87tgHafe",
"subject": "Email Subject",
"template_id": 3,
"to": {
"email": "j.smith@example.com",
"name": "John Smith"
},
"transactional": true
}
TransactionalEmailAddress: object
Describes an Email Address.
name: string
Name of the recipient.
email: string
Email of the recipient.
Example
{
"email": "j.smith@example.com",
"name": "John Smith"
}
TransactionalEmailContent: object
Describes the Email Content.
html: string
HTML version of the email.
text: string
Text version of the email.
Example
{
"html": "<html><head></head><body>Email content</body></html>",
"text": "Email content"
}
Recommended Data Schema
Although it is possible to name your data parameters to any values, we recommend to use the following schema for consistency.
|
Category |
Array |
Value |
Usage |
Example |
|
Contact |
contact |
|
Email address of the contact |
john@ometria.com |
|
phone |
The phone number of the contact |
07712312334 |
||
|
title |
The title of the contact |
Mr |
||
|
name |
First and Surname of contact |
John Smith |
||
|
firstname |
First name of the contact |
John |
||
|
surname |
Surname of the contact |
Smith |
||
|
contactID |
ID of the contact |
1234 |
||
|
accountUrl |
The URL to access the contacts account settings |
|||
|
Order |
details |
orderID |
The ID of the order placed |
00002501 |
|
creationDate |
The date and time the order was placed |
01/16/2019 9:50 am |
||
|
status |
The status of the order |
New |
||
|
orderDetailsUrl |
A link direct to the order details |
|||
|
coupons |
Coupon(s) used on the order |
Welcome10 |
||
|
payment |
paymentMethod |
The method of payment used |
Credit Card |
|
|
lastFour |
Last four digits on the credit card |
1111 |
||
|
amount |
The amount paid |
£1530 |
||
|
totals |
subTotal |
The subtotal for the order excluding shipping and tax |
£1530 |
|
|
totalShippingCost |
The shipping cost for the order |
£5 |
||
|
totalTax |
The tax cost for the order |
£5 |
||
|
grandTotal |
The total for the order including shipping and tax |
£1535 |
||
|
shipping |
address1 |
First line of address |
1 The Street |
|
|
address2 |
Second line of address |
West Quarter |
||
|
address3 |
Third line of address |
The Town |
||
|
city |
City of address |
London |
||
|
county |
County of address |
Greater London |
||
|
postcode |
Postcode of address |
EC1 1HY |
||
|
countrycode |
Country code of address |
GB |
||
|
trackingID |
The ID of the tracking service |
1223 |
||
|
trackingURL |
The URL of the tracking service |
|||
|
billing |
address1 |
First line of address |
1 The Street |
|
|
address2 |
Second line of address |
West Quarter |
||
|
address3 |
Third line of address |
The Town |
||
|
city |
City of address |
London |
||
|
county |
County of address |
Greater London |
||
|
postcode |
Postcode of address |
EC1 1HY |
||
|
countrycode |
Country code of address |
GB |
||
|
items |
imgUrl |
The URL of the product image to be used |
||
|
productID |
The ID of the product to be used |
12243563 |
||
|
colour |
The colour of the product |
Grey |
||
|
url |
The URL of the product on your website |
|||
|
quantity |
The quantity of the product purchased, refunded or added to wishlist |
1 |
||
|
sizeName |
The product size |
12 |
||
|
sizeDescription |
The description of the product size |
UK size 12 Trousers |
||
|
price |
The price of the product |
£25.00 |
||
|
discount |
The discount on the order |
£10 |
||
|
subTotal |
The price of the product multiplied by the quantity |
£25.00 |
||
|
length |
The length of the product |
short |
||
|
productName |
The name of the product |
Grey Trousers |
||
|
sku |
The SKU of the product |
grey_troursers |
||
|
Review |
review |
token |
The URL to submit the review |
|
|
reviewURL |
The URL of the review once submitted |
|||
|
Password |
password |
token |
The password reset token for the contact |
|
|
Misc |
message |
A string message to be included in an email |
Great to hear from you, we’ll look into your comments |
|
|
website |
A URL to your website (if different to you base URL in Ometria) |
Transactional Email HTML Examples
The next section of this document provides HTML examples that match the Postman collection provided. These examples can be used in your account for testing purposes.
- Order Confirmation
- Order Cancellation
- Review Order
- Review Success
- Forgot Password
- Update Password Success
- Contact Us
- Wishlist
- Wishlist Success
- Change Email to Old
- Change Email to New
- Your Account
- Catalogue Request
Order Confirmation
<HTML>
<body>
Order Confirmation - Example
<br><br>
Order Details:<br>
Order ID:{{ details.orderID }}<br>
Creation Date: {{ details.creationDate }}<br>
Email Address: {{ details.email }}<br>
Order Status: {{ details.status }}<br>
Order Detail URL: {{ details.orderDetailsUrl }}<br>
Order Coupons: {{ details.coupons }}<br>
<br><br>
Contact Details:<br>
Billing Contact (Title / firstname / surname):{{ contact.title }} {{ contact.firstname }} {{ contact.surname }} <br>
Billing Address 1:{{ billing.address1 }}<br>
Billing City:{{ billing.city }} <br>
Billing County:{{ billing.county }}<br>
Billing Postal Code:{{ billing.postalCode }} <br>
<br><br>
Delivery details:<br>
Shipping (firstname / surname): {{ shipping.firstname }} {{ shipping.surname }} <br>
Shipping Address1: {{ shipping.address1 }}<br>
Shipping City: {{ shipping.city }} <br>
Shipping PostalCode: {{ shipping.postalCode }} <br>
<br><br>
Payment Total:<br>
Subtotal: {{ totals.subTotal }}<br>
VAT inc./ Taxes: {{ totals.totalTax }} <br>
Shipping: {{ totals.totalShippingCost }} <br>
Total: {{ totals.grandTotal }} <br>
Payment Method: {{ payment.paymentMethod }}<br>
Amount: {{ payment.amount}}<br>
Last Four Digits: {{ payment.lastFour }}<br>
<br><br>
Order Items:
{% set max_items = 25 %}
{% for x in range(max_items) %}
{% if items[x] %}
<br><br>
Product Image: {{ items[x].imgUrl }}<br>
Product Name: {{ items[x].productname }}<br>
Quantity: {{ items[x].quantity }} <br>
Product Code: {{ items[x].productID }}<br>
Size:{{ items[x].sizeName }}<br>
Price: {{ items[x].price }}<br>
SKU: {{ items[x].sku }}<br>
{% endif %}
{% endfor %}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Order Cancellation
<html>
<body>
Order Cancellation - Example
<br><br>
Order Details:<br>
Order ID:{{details.orderID}}<br>
Order Status: {{details.status}}<br>
Order Detail URL: {{details.orderDetailsUrl}}<br>
<br><br>
Contact Details:<br>
Billing Contact (Title / firstname / surname):{{ contact.title }} {{ contact.firstname }} {{ contact.surname }} <br>
<br><br>
Message:<br>
{{ message.message }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Review Order
<html>
<body>
Review Order - Example
<br><br>
Contact Details:<br>
Review Contact (firstname): {{ contact.firstname }} <br>
Review Website: {{ contact.website }}
<br><br>
Review:<br>
Review URL: {{ review.reviewUrl }}<br>
Review Token:{{ review.reviewToken }}
<br><br>
Order Items:
{% set max_items = 25 %}
{% for x in range(max_items) %}
{% if items[x] %}
<br><br>
Product Image: {{ items[x].imgUrl }}<br>
Product Name: {{ items[x].productname }}<br>
Quantity: {{ items[x].quantity }} <br>
Product Code: {{ items[x].productID }}<br>
Size:{{ items[x].sizeName }}<br>
Price: {{ items[x].price }}<br>
SKU: {{ items[x].sku }}<br>
{% endif %}
{% endfor %}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Review Success
<html>
<body>
Review Success - Example
<br><br>
Contact Details:<br>
Review Contact (firstname): {{ contact.firstname }}
<br><br>
Review:<br>
Review URL: {{ review.reviewUrl }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Forgot Password
<html>
<body>
Forgot Password - Example
<br><br>
Contact Details:<br>
Password Contact (firstname): {{ contact.firstname }}<br>
Password Email: {{ contact.email }}
<br><br>
Password:<br>
Password URL: {{ password.token }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Update Password Success
<html>
<body>
Update Password Success - Example
<br><br>
Contact Details:<br>
Password Contact (firstname): {{ contact.firstname }}<br>
Password Email: {{ contact.email }}
<br><br>
Website:<br>
Website URL: {{ contact.website }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Contact Us
<html>
<body>
Contact us - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact Email: {{ contact.email }}<br>
Contact Country Code: {{ contact.countrycode }}<br>
Website URL: {{ contact.website }}<br>
Message: {{ contact.message }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Wish List
<html>
<body>
Wish List Success - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact Email: {{ contact.email }}
<br><br>
Referree:
Referree (firstname): {{ referree.firstname }}<br>
Referree Email: {{ referree.email }}
<br><br>
Message: {{ message.message }}
<br><br>
Wish List Items:
{% set max_items = 25 %}
{% for x in range(max_items) %}
{% if items[x] %}
<br><br>
Product Image: {{ items[x].imgUrl }}<br>
Product Name: {{ items[x].productname }}<br>
Quantity: {{ items[x].quantity }} <br>
Product Code: {{ items[x].productID }}<br>
Size:{{ items[x].sizeName }}<br>
Price: {{ items[x].price }}<br>
SKU: {{ items[x].sku }}<br>
{% endif %}
{% endfor %}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Wish List Success
<html>
<body>
Wish List Success - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact Email: {{ contact.email }}
<br><br>
Referree:
Referree (firstname): {{ referree.firstname }}<br>
Referree Email: {{ referree.email }}
<br><br>
Message: {{ message.message }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Change Email to New
<html>
<body>
Email Change - Email to New Email Address - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact New Email: {{ contact.email }}<br>
Contact Old Email: {{ contact.oldemail }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Change Email to Old
<html>
<body>
Email Change - Email to Old Email Address - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact New Email: {{ contact.newemail }}<br>
Contact Old Email: {{ contact.email }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Your account
<html>
<body>
Your Account - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact Account URL: {{ contact.accountURL }}
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Catalogue Request
<html>
<body>
Catalogue Request - Example
<br><br>
Contact Details:<br>
Contact (firstname): {{ contact.firstname }}<br>
Contact Account URL: {{ contact.accountURL }}
<br><br>
Delivery details:<br>
Shipping (firstname / surname): {{ shipping.firstname }} {{ shipping.surname }} <br>
Shipping Address1: {{ shipping.address1 }}<br>
Shipping City: {{ shipping.city }} <br>
Shipping PostalCode: {{ shipping.postalCode }} <br>
<br><br>
<!-- <a href="{{unsub}}">Click Here</a> -->
</body>
</html>
Comments
0 comments
Please sign in to leave a comment.