API Version Usage Recommendation


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.


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:

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!


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 parameterDescription
response_typeAuthorization code grant type. Always pass code.
client_idYour OAuth client id.
redirect_uriURL where user will be redirected with generated auth code.
scopesThe resources your app is willing to access. Values separated by spaces. They are defined for each endpoint in our API documentation.
stateRandomly generated, unique per request value used by your app to maintain state between request and callback. More info: "state" Parameter.


GET https://app.omnisend.com/oauth2/authorize?client_id=YOUR_CLIENT_ID

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:


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 parametersDescription
codeThe code parsed from the URL
grant_typeAlways must be authorization_code
client_idYour OAuth client id
client_secretYour OAuth client secret
redirect_uriSame redirect URI used in the step 2


POST https://app.omnisend.com/oauth2/token
Content-Type: application/x-www-form-urlencoded


You will get a similar response:

  "expires_in": 9223372036,
  "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

As you got familiar with the authentication and actual requests to our API, you can now start exploring other endpoints.

API Reference

P.S. If you have any feedback, or you are missing some important information, please contact us via [email protected].