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

Version 1.0

The following instructions are made for custom subscribe forms to be integrated with Omnisend. These instructions will allow you to connect any type of subscribe form on your website (the type of website is irrelevant) with your Omnisend account.

There are two main steps you need to complete:

  • Embed the Snippet on your website. If you do already have our Snippet, you do still need to add this one too.
  • Either embed the Basic form or implement the Advanced form.

Snippet

Shippet helps us to track forms correctly. To add a Snippet to your website, you need to embed JavaScript code (provided below) at the end of EVERY page of your website.

Then paste your brandID into the line #3. To retrieve your brandID, please contact support@omnisend.com.

<script type="text/javascript">
    window.SOUNDEST = window.SOUNDEST || {};
    SOUNDEST.brandID = "XXXXXXXXXXXXXXXXXXXXXXXX";
    SOUNDEST.baseURL = "https://omnisrc.com/";
    SOUNDEST.version = new Date().toISOString().slice(0, 13);
    (function() {
        function asyncLoad() {
            var ss = document.createElement("script"); ss.type = "text/javascript"; ss.id = "soundest-external-launcher"; ss.async = true;
            ss.src = SOUNDEST.baseURL + "inshop/external-launcher.js?v=" + SOUNDEST.version;
            var sc = document.getElementById("soundest-external-container");
            sc.parentNode.insertBefore(ss, sc);
        }
        window.attachEvent ? window.attachEvent("onload", asyncLoad) : window.addEventListener("load", asyncLoad, false);
    })();
</script>
<div id="soundest-external-container"></div>
If you do not know your brandID, contact us at support@omnisend.com.

Basic form

This is a basic version of the form. You are able to change lists, attributes, translate messages and define your own styles. All the requests and actions are handled by us.

You need to put HTML code (provided below) wherever you want your form to appear.

<form class="soundest-form">
	<input class="soundest-form-list" type="hidden" value="YYYYYYYYYYYYYYYYYYYYYYYY" />
	<input class="soundest-form-list" type="hidden" value="ZZZZZZZZZZZZZZZZZZZZZZZZ" />
	<div class="soundest-form-attributes">
		<input class="soundest-form-attribute" name="email" type="text" placeholder="Your email address" />
		<input class="soundest-form-attribute" name="firstName" type="text" placeholder="Your first name" />
		<input class="soundest-form-attribute" name="lastName" type="text" placeholder="Your last name" />
		<select class="soundest-form-attribute" name="gender">
			<option value="m">Male</option>
			<option value="f">Female</option>
		</select>
		<input class="soundest-form-attribute" name="address" type="text" placeholder="Your address" />
		<input class="soundest-form-attribute" name="city" type="text" placeholder="Your city" />
		<input class="soundest-form-attribute" name="country" type="text" placeholder="Your country" />
		<input class="soundest-form-attribute" name="phone" type="text" placeholder="Your phone" />
		<input class="soundest-form-attribute" name="birthdate" type="text" placeholder="Your birthdate" />
		<input class="soundest-form-attribute" name="shopID" type="text" placeholder="Your ID" />
		<input type="submit" value="Subscribe!">
	</div>
	<div class="soundest-form-loading">Please wait...</div>
	<div class="soundest-form-success">Thank you!</div>
	<div class="soundest-form-error-empty">Fill in data!</div>
	<div class="soundest-form-error-invalid">Data is invalid!</div>
	<div class="soundest-form-error-unexpected">Unexpected error occurred!</div>
</form>

In the lines #2-3 you can define the exact lists, where you want your subsribers to appear. It is possible to leave only one list or remove all of them. Read more about lists.

In the lines #5-17 you can define attributes your subscribers are required to fill. You are welcome to delete attributes you do not need and leave, for instance, only email and first name (lines #5-6). The attributes you leave are all mandatory for a subscriber to fill in. Read more about attributes.

In the lines #20-24 you can translate the messages, shown by the form.

Message Appearance
soundest-form-loading When subscriber clicks the subscribe button and waits for the response from us.
soundest-form-success When subscriber successfully subscribes.
soundest-form-error-empty When subscriber clicks the subscribe button and there are empty fields left.
soundest-form-error-invalid When subscriber clicks the subscribe button and there are fields filled with invalid data.
soundest-form-error-unexpected When subscriber clicks the subscribe button and server-side error occurs.

To be able to style the form, you need to put CSS code (provided below) either at the end of EVERY page or in your CSS file.

<style type="text/css">
	/* DO NOT CHANGE THESE LINES */
	.soundest-form-loading,
	.soundest-form-success,
	.soundest-form-error-empty,
	.soundest-form-error-invalid,
	.soundest-form-error-unexpected {
		display: none;
	}
	/* YOU CAN CHANGE THESE LINES */
	.soundest-form {
		width: 100%;
		max-width: 350px;
	}
	.soundest-form,
	.soundest-form input,
	.soundest-form select {
		color: #5c5c5c;
		font-size: 15px;
		font-family: Arial, sans-serif;
	}
	.soundest-form input,
	.soundest-form select {
		width: 100%;
		height: 43px;
		display: block;
		padding: 10px;
		border: 2px solid #dcdcdc;
		background-color: #ffffff;
		outline-width: 0px;
		margin-bottom: 5px;
		-webkit-appearance: none;
		-webkit-box-sizing: border-box;
		-moz-box-sizing: border-box;
		box-sizing: border-box;
		-webkit-border-radius: 5px;
		-moz-border-radius: 5px;
		border-radius: 5px;
	}
	.soundest-form input:focus,
	.soundest-form select:focus {
		border: 2px solid #b5b5b5;
	}
	.soundest-form input[type="submit"] {
		color: #ffffff;
		font-size: 16px;
		font-weight: bold;
		border: 2px solid #a2a2a2;
		background-color: #a2a2a2;
		cursor: pointer;
	}
	.soundest-form input[type="submit"]:focus {
		border: 2px solid #6a6a6a;
		background-color: #6a6a6a;
	}
	.soundest-form .soundest-form-attribute-empty,
	.soundest-form .soundest-form-attribute-invalid {
		border: 2px solid #f44444;
	}
	.soundest-form-loading,
	.soundest-form-success,
	.soundest-form-error-empty,
	.soundest-form-error-invalid,
	.soundest-form-error-unexpected {
		padding: 15px 0px;
		text-align: center;
	}
</style>

You are welcome to change the CSS however you like.

Advanced form

This is an advanced version of the form. Everything is in your hands, including changing lists, attributes, handling callbacks. We provide API which you are supposed to use with your own form.

You need to execute JavaScript code (provided below) everytime a subscriber needs to be created or updated.

window.SOUNDEST_EVENTS = window.SOUNDEST_EVENTS || [];
SOUNDEST_EVENTS.push(["forms", "submit", {
	lists: [
		"YYYYYYYYYYYYYYYYYYYYYYYY",
		"ZZZZZZZZZZZZZZZZZZZZZZZZ"
	],
	attributes: {
		email: "aaa@bbb.com",
		firstName: "aaa",
		lastName: "bbb",
		gender: "m",
		address: "ccc",
		city: "ddd",
		country: "eee",
		phone: "44XXXXXXXXXX",
		birthdate: "YYYY-MM-DD",
		shopID: "fff"
	},
	callbacks: {
		onSuccess: function(response) {
			console.log(response);
		},
		onError: function(response) {
			console.log(response);
		}
	}
}]);

In the lines #3-6 you can define lists where you want your subsribers to appear. It is possible to leave only one list or remove all of them. Read more about lists.

In the lines #7-18 you can define attributes of your subscribers. You are welcome to delete attributes you do not need and leave, for instance, only email and first name (lines #8-9). Read more about attributes.

In the lines #19-26 you can define what happens on successful subscription and on failure.

Callback Appearance Response
onSuccess When subscriber successful subscribes.
{
	code: 0,
	message: "ok",
	data: {
		contactID: "XXXXXXXXXXXXXXXXXXXXXXXX",
		isNew: true,
		couponCode: "AAABBB"
	}
}

In the line #2 you get response code.

In the line #3 you get brief response message.

In the line #5 you get contactID in our system.

In the line #6 you get whether subscriber is new or just providing more information.

In the line #7 you get coupon code if Coupon Pop Up feature is turned on.

It may take some time (usually, up to 5 minutes) for coupon code to appear after Coupon Pop Up feature is turned on.
onError When error occurs while trying to subscribe.
{
	code: 3,
	message: "data is missing",
	data: {
		missingAttributes: ["email"],
        invalidAttributes: ["birthdate"],
        invalidLists: ["ABC"],
        missingSettings: ["brandID"]
	}
}

In the line #2 you get a response code.

In the line #3 you get a brief response message.

In the lines #5-8 you get arrays of missing or invalid attributes, lists or settings.

Response code Response message
0 ok
1 parameters are missing
2 parameters are invalid
3 data is missing
4 data is invalid
5 settings are missing
6 settings are invalid
7 request failed

More info

Lists

Lists allows to categorize your subscribers.

You can create a list on your Omnisend account by going to Shoppers > Import lists tab.

You can get the ID of a list on Settings tab of a certain list.

Attributes

Attributes define specific information about a user. You can use either attributes from the list provided bellow to acquire information from your subscribers.

Attribute Required Validation
email Yes -
firstName No -
lastName No -
gender No m or f
address No -
city No -
country No -
phone No 44XXXXXXXXXX
birthdate No YYYY-MM-DD
shopID No -