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

Send Transactional Email

Transactional Email objects

Transactional Email object

Transactional Email Address object

Transactional Email Content object

Transactional Examples

Recommended Data Schema

Transactional Email HTML Examples

Send Transactional Email

Path

POST /transactional-email/send

Description

Send a transactional email.

Request Body

TransactionalEmail

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": "Orders",
  "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.

to: TransactionalEmailAddress 

from: TransactionalEmailAddress 

reply_to: TransactionalEmailAddress

You can include data from the API 'data' element in the subject line using the following notation:

Thank you for order {{details.orderID}}

Note: This notation is case sensitive, so if the parameter is OrderID, you should use {{{details.OrderID}}.

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	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	www.ometria.com/myaccount/12345
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	www.ometria/s/brand/orders
		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	www.ometria.com/tracking/1223
	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	https://www.ometria.com/img/12243563.jpg"
		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	https://www.ometria.com/product/12243563.html
		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	www.ometria.com/review/12345
		reviewURL	The URL of the review once submitted	www.ometria.com/review/12345
Password	password	token	The password reset token for the contact	www.ometria.com/reset/12345
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)	www.ometria.com

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>