API Version Usage Recommendation
Introduction
Welcome to the Omnisend API! We highly recommend using our v3 API version for new projects due to its stability, feature-rich capabilities, and ongoing support and development. While v4 version is available and does support OAuth authorization, we advise against using it for new projects.
Reasoning
The v4 API version is not recommended for new projects primarily because we are planning to integrate its functionalities and improvements into the more robust v3 version. This will ensure a seamless and enhanced experience for our users.
Transitioning to v3
To make use of OAuth authorization and benefit from the upcoming improvements, we strongly recommend integrating with our v3 API version. Our team is actively working on incorporating the features from v4 into v3, ensuring that you have access to the latest advancements without disrupting your integration.
Contacting Support
If you still wish to integrate with the v4 API version, please reach out to our support team. They will be more than happy to assist you and provide guidance on the best approach for your project.
We appreciate your understanding and cooperation in helping us provide you with the best API experience. If you have any questions or need further assistance, feel free to contact our support team at [email protected].
General information
We will walk you through the steps needed to get started including app submission, authentication and some sample requests to our API.
Before jumping to the steps, we would like to highlight which resources can be reached via our API:
- Contacts - identify/create, get details
- Events - track any event around the contact (e.g., "page viewed", "product ordered", etc)
Ok, lets get started!
Registering your app
First, you'll need to register your application. Go to Partners Portal and submit a form.
The most important part here is a Authorization callback URL where the auth code will be delivered after the successful user authorization.
After sending us all the required data, we will reach you out with app details such as unique Client ID and Secret. The Client Secret should not be shared!
Now you are ready to build your integration!
Authentication
As you probably already noticed from the previous step, our API is secured with OAuth 2.0. Meaning that your app must implement Authorization Code Grant flow standard in order to get access tokens on behalf of users.
1. Generating an auth request
Now you have to generate Authorization request with these query parameters:
| Query parameter | Description |
|---|---|
response_type | Authorization code grant type. Always pass code. |
client_id | Your OAuth client id. |
redirect_uri | URL where user will be redirected with generated auth code. |
scopes | The resources your app is willing to access. Values separated by spaces. They are defined for each endpoint in our API documentation. |
state | Randomly generated, unique per request value used by your app to maintain state between request and callback. More info: "state" Parameter. |
E.g.:
GET https://app.omnisend.com/oauth2/authorize?client_id=YOUR_CLIENT_ID
&redirect_uri=REDIRECT_URI
&response_type=code
&state=RANDOMLY_GENERATED_VALUE
&scope=RESOURCEX%20RESOURCEY
If a user is not logged in, she/he will be redirected to do that. After logging in, consent page will be shown.
Here the user will need to give an approval for the app to access particular resources on behalf of her/him. Continuing the flow brings the user to the next step.
2. Accepting user authorization
Do you remember the Authorization callback URL specified during app submission? The user will now be redirected to that URL, and you are responsible for taking care of the auth code provided in query parameters.
E.g., of the callback:
http://localhost:6000/?code=6O-KEB2KNCWKT7YVFYTF9G&state=adxcsasdcqws
You must parse the code and proceed to the next step.
3. Getting an access token
With the code from previous step you need to generate a POST request to exchange the code to an access token.
| Body parameters | Description |
|---|---|
code | The code parsed from the URL |
grant_type | Always must be authorization_code |
client_id | Your OAuth client id |
client_secret | Your OAuth client secret |
redirect_uri | Same redirect URI used in the step 2 |
E.g.:
POST https://app.omnisend.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=REDIRECT_URI
You will get a similar response:
{
"access_token": "RANDOMLY_GENERATED_ACCESS_TOKEN",
"expires_in": 9223372036,
"refresh_token": "RANDOMLY_GENERATED_REFRESH_TOKEN",
"scope": "RESOURCEX RESOURCEY",
"token_type": "Bearer"
}
That's it! You now have an access token for requested resources for the particular user. Keep it as long as you need, because it will never expire (unless the user will decide to revoke it).
Making a request to the API
With an access token you can start calling our API and interact with resources (such as Contacts, Events, etc).
Here is a sample request to get a contact by provided email:
GET https://api.omnisend.com/v4/contacts/email:[email protected]
Content-Type: application/json
Authorization: Bearer RANDOMLY_GENERATED_ACCESS_TOKEN
As you got familiar with the authentication and actual requests to our API, you can now start exploring other endpoints.
P.S. If you have any feedback, or you are missing some important information, please contact us via [email protected].