Introduction

The Transactional API is used to trigger instant email messages to recipients. 

General Considerations

Ometria API is restricted to 4 calls per second for sending transactional emails.

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

Postman Collection


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


to: TransactionalEmailAddress 

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.

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>


Transactional Email PostMan Collection

The Postman collection can be used in conjunction with the HTML examples provided on this page.