Please use our new API v3. Current API will be discontinued on Jul 1st, 2018.
Version 1.9

About Omnisend

Omnisend is easy to use email marketing service designed for ecommerce sites. It seamlessly integrates with ecommerce website and helps to make email marketing easier:

  • We automatically synchronize the subscribers and customers so there is no need to import a file.
  • We provide a tool to create beautiful newsletters and with Product picker make it happen very quickly: it is done just by browsing the store and selecting the needed products. A few clicks and a product with all it's information and photo is neatly placed in the newsletter.
  • We do automatic segmentation: according to the clicks, opens and synchronized purchase data from the store we help to identify the suspects, prospects, new customers, regular customers, best customers and those who left.

We also offer a handful of marketing tools and scenarios to help spend less time yet achieve even better results. To know more visit us at www.omnisend.com.



Integration

Integrating Omnisend with an e-commerce website is quite easy. The whole process consists of authorization and registration, customer info synchronization, Product picker, Sales tracking and Cart Recovery integration along with product and order info synchronization.

Everything begins with authorization after which a user will be forwarded to the registration. After the successful registration an account will be created and synchronization processes will be initiated.



Authorization

First of all, you need to forward your user to the registration window. During this procedure, an authorization process will commence. The forwarding is done by using the URL https://login.omnisend.com/REST/authorize/custom with the GET or POST parameters provided in the Table 1 (more about GET and POST). You will also need to have an apiEndpoint for further steps to be implemented correctly. apiEndpoint should exist prior to the registration.

Parameter Comment Required?
shopURL Link to shop main page (e.g. http://www.yourshopdomain.com) Yes string
apiEndpoint Link to shop API used by Customers, Products and Orders (e.g. http://www.yourshopdomain.com/api/someSecretApiKey) Yes string
publicApiEndpoint Link to shop public API (no API key is needed) used by Cart Recovery (e.g. http://www.yourshopdomain.com/api/public) Yes string
shopID Shop ID, should be unique per partner. Any numeration can be used, yet cannot repeat. Yes string or integer
currency Main currency code used in shop (e.g. EUR, USD) Yes string
language Shop owners language (currently supporting "en" only) Yes string
inSiteEnabled 1 - use Product picker, 0 - do not use Product picker. More about Product picker Yes int
platformName You should enter one of these: magento, oxid, woocommerce, opencart, zencart, oscommerce, ubercart, prestashop, virtuemart. If your platform is not listed above, please enter "other". For more information contact support@omnisend.com Yes string
sso 1 - use single sign-on, 0 - do not use single sign-on. More about Single sign-on No int
partnerID Partner ID can be retrieved by contacting dev@omnisend.com No string
email User email. Will be used for logging in if SSO is not implemented. No string
firstName User first name No string
lastName User last name No string
organisationName The name of the client's company No string
country User country No string
city User city No string
street User street No string
streetNumber User street number No string
zipCode User zip code No string
timezone User timezone name in TZ format (e.g. "Europe/London", "Asia/Tokyo") No string

Example:

https://login.omnisend.com/REST/authorize/custom?shopURL=http://yourshopdomain.com/&apiEndpoint=http://www.yourshopdomain.com/api/someSecretApiKey&publicApiEndpoint=http://www.yourshopdomain.com/api/public&shopID=1&currency=EUR&language=en&inSiteEnabled=1&platformName=other&partnerID=partnerIDReceivedFromSupport

By clicking on this URL a user will be redirected to registration form. After registration all data will be saved for further usage. If registration was successful this callback URL will be called by us:

GET apiEndpoint/registrationComplete

After successful registration user will need to access https://app.omnisend.com to log into the system (he will be asked to provide email address and password). However, to avoid this single sign-on can be used.



Single sign-on

Single sign-on can be used to create a smoother experience. There will be no need to use a login page, if single sign-on is implemented. If a partner wants to use single sign-on, that partner must have partnerID and partnerSecret retrieved from our support. You can do it by contacting us at dev@omnisend.com.

To make single sign-on work, you will need to forward you users (user needs to be registered already) to https://login.omnisend.com/REST/authorize/custom with following GET parameters:

Parameter Comment
partnerID partnerID is the same as used the first time during the registration
shopID shopID is the same as used the first time during the registration
timestamp Current timestamp. ISO 8601 time with timezone. Timestamp must not be older than 60 seconds.
signature SHA512 hmac from string "<partnerID>|<shopID>|<timestamp>" (first three parameters joined with "|"), secret key is partnerSecret. Order of parameters in string is important!

Example

https://login.omnisend.com/REST/authorize/custom?partnerID=partnerIDReceivedFromSupport&shopID=1&timestamp=2014-01-01T00:00:00.000Z&signature=generatedSignatureUsingSHA512HMAC

Once it is done, user should be able to get logged in without being prompted to provide log in info.



Customers

Customer info is being synchronized to Omnisend for automatic population of contact list (both subscribers and customers). All data gets synchronized right after the registration and renewed daily at approximately 1 AM (depending on the time zone). When data synchronization is initiated we will make a request to you with the following URL:

A brand will get suspended, if the list cannot be synchronized for more than a few days in a row. It will be suspended and no imports will be done until the next login. The list of import can be empty. In case of an error we treat it as a failed import (e.g. Error 404, Error 500, etc.)
apiEndpoint - should be defined prior the registration

GET apiEndpoint/getClients/<amountPerPage>/<pageNumber>

Parameter Comment
amountPerPage Amount of customers to be provided. If the supplier will provide fewer customers than it says - our system will assume that the list is complete
pageNumber Starts from 1 and incrementing by 1 on each request

Response should be valid JSON array

[customer1, customer2, ... customerN]

Each customer should have an email. All other attributes, provided in the table below are optional, but the more info you have, the better marketing can be done.

Attribute Type Comment
email string Email address is required!
eshop_id string Customer identifier or his number
first_name string First name of your contact
last_name string Last name of your contact
gender string Use values "m" and "f" (m - male, f - female)
address string -
city string -
country string -
phone string -
birthdate string Date ISO 8601
opt_in string Date when customer subscribed ISO 8601 (date, time and timezone e.g. 2014-01-01T01:30:00.000Z)
opt_out string Date when customer unsubscribed ISO 8601 (date, time and timezone e.g. 2014-01-01T01:30:00.000Z)
eshop_not_subscribed int Values 0 and 1. Use 1 if your contact does NOT want to receive newsletters.
orders array Each order should be object with properties {"id":(string),"date":(ISO 8601 string),"sum":(float)}
lists array Array of strings with imports lists' IDs
universal string A custom (single) parameter of your choice which allows you to create custom segments. For example you want to segment people by their interest. In this case Subscriber A will have "sports" (as the value of Universal parameter), Subscriber B will have "travel" (as the value of Universal parameter)

This process is initiated right after the registration and once a day. It is important to have everything set up prior the registration so that the initial data import would go successfully.



Products

apiEndpoint - should be defined prior the registration

To make Product picker and Cart Recovery work properly, info of the product has to be made accessible to Omnisend. When data synchronization is initiated (when the Product picker is in use or Cart Recovery is creating a letter), we will make a request to the following URL:

GET apiEndpoint/getProduct/<productID>

Parameter Comment
productID Product ID received from the Snippet

Response should be valid JSON object

{"productID":12345,"link":"http://yourshopdomain.com/products/12345","image":"http://yourshopdomain.com/images/12345.png","title":"Awesome product","desc":"<p>This is an <b>amazing</b> product.</p>","price1":99,"price2":199}
Attribute Type Comment
productID string/int ID of the product
link string Link to the product page
image string Link to the product image (PNG, JPG or GIF format). Width of the image should be at least 560px.
title string Title of the product
desc string Description of the product. Description should not be longer then 30 words (only a, strong, b, i, em, span, p and br HTML tags allowed)
price1 float Current price of the product
price2 float "Old" price of the product which is used as discount. 0 to use only the current price.


Snippet

To make Product picker, Sales tracking and Cart Recovery work, you will need to add JavaScript snippet (provided lower) at the end of EVERY shop page.

<script type="text/javascript">
    var soundestInShop = {};
    soundestInShop.productID = "";
    soundestInShop.products = [];
    soundestInShop.additionalData = {};
    soundestInShop.shopType = "custom";
    soundestInShop.baseURL = "https://omnisrc.com/";
    soundestInShop.version = new Date().toISOString().slice(0, 13);
    (function() {
        var se = document.createElement("script"); se.type = "text/javascript"; se.async = true; se.src = soundestInShop.baseURL + "inShop/launcher.js?v=" + soundestInShop.version;
        var ss = document.getElementsByTagName("script")[0]; ss.parentNode.insertBefore(se, ss);
    })();
</script>

You will also need to add JavaScript snippet (provided lower) at the end of the THANK YOU page. Tip: THANK YOU page is the page which is seen before user is redirected to Payment Gateway's page. This way we will also track orders that used "Cash on delivery" payment method.

<script type="text/javascript">
    (function(e,t,n){try{var r=new Date,i=location.hostname.replace(/^www./i,""),s=["timestamp="+(new Date).getTime(),"shopBaseURL="+window.location.protocol+"//"+window.location.hostname+"/","orderID="+n,"shopType="+t,"source=jsPixel"],o,u;try{o=document.cookie.replace(/(?:(?:^|.*;\s*)soundestID\s*\=\s*([^;]*).*$)|^.*$/,"$1");if(o!==""){s.push("sID="+o)}}catch(a){}try{r.setTime(r.getTime()+90*24*60*60*1e3);document.cookie="soundest-sales-"+n+"="+(new Date).toISOString()+"; expires="+r.toUTCString()+"; path=/; domain=."+i}catch(a){}u=document.createElement("img");u.src=e+"?"+s.join("&");u.onload=function(){try{document.cookie="soundest-sales-"+n+"=; expires="+(new Date(0)).toUTCString()+"; path=/; domain=."+i}catch(e){}};document.body.appendChild(u);window.soundestInShopSales=true}catch(a){}})("https://events.soundestlink.com/events/saveNewsletterOrder/","custom","[orderID]");
</script>


Product picker

Product picker is a tool that allows to add a product with all of it's info to the newsletter in a very convenient way - by just browsing your store. A widget will appear there (only seen to the shop owner) and allow the addition of the product with a click of a few buttons.

On the product page a variable soundestInShop.productID (defined in the Snippet column) should contain the ID of that certain product. On other pages (non-product pages) the variable should be an empty string.

<script type="text/javascript">
    ...
    soundestInShop.productID = "12345"; // on the product page
    soundestInShop.productID = ""; // on other pages
    ...
</script>
Identifier (ID) of the product should be the same as identifier used in Products request.



Orders

apiEndpoint - should be defined prior the registration

To make Sales tracking work properly, info about order has to be made accessible to Omnisend. When order is placed, we will make a request to the following URL:

GET apiEndpoint/getOrder/<orderID>

Parameter Comment
orderID Order ID received from the Snippet

Response should be valid JSON object

{"id":12345,"created":"2014-01-01T01:30:00.000Z","total":123.45,"products":[{"id":123,"quantity":1,"price":179.8},{"id":456,"quantity":2,"price":239.7},{"id":789,"quantity":3,"price":15.9}]}
Attribute Type Comment
id string/int ID of the order
created string Date when order was placed ISO 8601 (date, time and timezone e.g. 2014-01-01T01:30:00.000Z)
total float Total price of the order
products array List of the products. Each product should be an object with properties {"id":(string/int),"quantity":(int),"price":(float)}
Identifier (ID) of the product should be the same as identifier used in Products request.


To make Cart Recovery work properly, info about orders made by a user with specific sID or email has to be made accessible to Omnisend. When a cart is being checked whether it is abandoned or not, we will make a request to one of the following URLs:

GET apiEndpoint/getOrders/sID/<sID>

GET apiEndpoint/getOrders/email/<email>

Parameter Comment
sID sID received from the cookie soundestID
email Email of subscriber
sID - soundestID - random hash generated by the Snippet and saved as one of the cookies of the store. When order is placed the hash should be saved as part of the information of the order.
There can be more than one order with the same sID.

Response should be valid JSON array

[order1, order2, ... orderN]
{"id":12345,"created":"2014-01-01T01:30:00.000Z","total":123.45,"products":[{"id":123,"quantity":1,"price":179.8},{"id":456,"quantity":2,"price":239.7},{"id":789,"quantity":3,"price":15.9}]}
Attribute Type Comment
id string/int ID of the order
created string Date when order was placed ISO 8601 (date, time and timezone e.g. 2014-01-01T01:30:00.000Z)
total float Total price of the order
products array List of the products. Each product should be an object with properties {"id":(string/int),"quantity":(int),"price":(float)}
Identifier (ID) of the product should be the same as identifier used in Products request.


Sales tracking

Sales tracking allows you to see, how much each of your newsletters have earned for you. Omnisend will track the successful orders and provide you with a total sum received from a specific newsletter.

On the "thank you" page an argument [orderID] (defined in the Snippet column) should contain an ID of that specific order. On other pages (non-"thank you" pages) the second snippet should not be displayed. Tip: THANK YOU page is the page which is seen before user is redirected to Payment Gateway's page. This way we will also track orders that used "Cash on delivery" payment method.

<script type="text/javascript">
    (function(e,t,n) ... "custom","123456"); // on the "thank you" page
</script>
Identifier (ID) of the order should be the same as identifier used in Orders request.


Cart Recovery

Cart Recovery helps to turn abandoned carts into orders. An automatic email reminder with selected products is sent to shoppers who added them to cart, but didn't make a purchase.

On EVERY page a variable soundestInShop.products (defined in the Snippet column) should be an array of products, which are in the cart, containing their IDs and quantities. If the cart is empty, the variable should be an empty array.

soundestInShop.products = [{"id":123,"quantity":1},{"id":456,"quantity":2}]; // if the cart is not empty
soundestInShop.products = []; // if the cart is empty


On EVERY page a variable soundestInShop.additionalData (defined in the Snippet column) should contain an email address of logged in user or the one who filled in the form during the purchase process.

soundestInShop.additionalData = { email: 'example@example.com' };


publicApiEndpoint - should be defined prior the registration

To make Cart Recovery work properly, shop should be able to recreate specific cart when it is needed. When a user clicks on the recovery link, we will redirect to:

GET publicApiEndpoint/recoverCart/<encoded array of the products>

Parameter Comment
encoded array of the products Base64-encoded array of products containing their IDs and quantities
publicApiEndpoint/recoverCart/W3siaWQiOjEyMywicXVhbnRpdHkiOjF9LHsiaWQiOjQ1NiwicXVhbnRpdHkiOjJ9XQ== // [{"id":123,"quantity":1},{"id":456,"quantity":2}]

Actions that should be done:

  1. Read and decode the array of products from the link
  2. Clear current cart of a user
  3. Create cart for the user filled with decoded products
  4. Redirect the user to the page of the cart

If it is impossible to recreate the cart (specific platform cannot do that or data is corrupted), user should be redirected to the main page of the shop.