Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

About API

Вы здесь:

UniSender API is a special interface for developers, which allows you to integrate the possibility of – email campaigns with almost any open-source web service or a desktop application. Our API provides contact list managing, creation and sending of various types of messages and obtaining campaign’s statistics. Partner and reseller schemes can also be set up by the API.

Working with API is free for all accounts. It is enough to enable the access to it and get API key in your Personal account. The API key is confidential and should not be passed to others or be visible in the web page’s source code, due to the possibility of illegal usage for sending emails on your behalf.

UniSender API for your business

Properly made UniSender integration will greatly simplify email marketing for your company. You won’t have to manually synchronize lists all the time and everything will be done automatically. Automation examples:

  • automatic adding of all new customers from your online store into a UniSender list;
  • synchronization of contacts’ statuses with your existing CRM;
  • creation of special sections for the delivery of electronic mailing services to Internet portals;
  • downloading of campaigns’ statistics into the systems of analysis and data mining;

The principle of API usage

Make an HTTPS request to the URL of the following type:

https://api.unisender.com/LANG/api/METHOD?format=json&api_key=KEY
&arg1=ARG_1&argN=ARG_N

where:

  • LANG * – the language of API server messages, ru, en, it are possible at the moment;
  • METHOD * – the name of the method;
  • KEY * – API access key;
  • ARG_1 … ARG_N – parameters’ values.

All the parameters must be encoded in UTF-8. In the example above the parameters are indicated in the GET request, but you can pass them in the POST request. Moreover, we strongly recommend passing the parameter API_key through POST request to avoid its storing in proxy servers’ logs.

UniSender API responds with JSON objects.

Both the request and the response can be compressed by gzip or bzip2 algorithms.

The response for a successful method call:

If the call was successful the object contains a field “result“, the content of this field depends on the called method. Even in case a of successful method call, field “warnings” may appear, containing an array of objects-warnings with a single string field “warning”.

If the call was unsuccessful instead of “result” there will be a field “error”.

Successful API call response example:

{
  "result":{
    "message_id":34423432
  },
  "warnings":[
    {"warning":"probably not a mobile phone"}
  ]
}

Unsuccessful API call response example:

{"error":"AK100310-02","code":"invalid_api_key"}

To catch the error during the method performance, the field “error” with the HTML message about the error will appear in the object of response. The object of error response also contains the field “code” with an error code string.

Standard error codes:

codes meaning
unspecified the error type is not indicated. See the report for details
invalid_api_key the invalid API key was passed. Check whether the api_key value matches with the one in  your account
access_denied access is denied. Check whether the access to API is enabled in your account and consider if you are allowed to use the method you are calling to
unknown_method incorrect method name passed
invalid_arg incorrect parameter passed
not_enough_money there is not enough money to perform an action
retry_later temporary failure. Please try again later
api_call_limit_exceeded_for_api_key API calls’ limit is exceeded. 300 calls per minute are available

In addition to these errors, there may be others which are specified in the description of methods.

List of methods

Working with contact lists

Creating and sending messages

Getting statistics

System Event Notification – Webhooks

To solve the problem of status change notification of delivery, we have made a new API, which will make it possible to register and manage the alerts’ handlers, so-called Webhooks.

The procedure of methods calls

You can have one or more lists; it is assumed that each list corresponds to a specific list of a campaign’s topic and your client can be subscribed to one list and not subscribed to another one.

Before sending an email or SMS to the recipients of a particular list, you are to know the list’s code using the getLists method, or create a new list using the createList method. Then you have to add contacts to the list – either using the method of mass import – importContacts, or one by one using the subscribe method.

Then you can send messages. You have to create the message using the createEmailMessage (or createSmsMessage) method. You specify the list id with the addressees and the letter will be targeted to all the recipients in the list, who were active at the moment of request to the createEmailMessage / createSmsMessage method. If it is an automated email, which is included into the batch like “Step by Step Weight Loss in 10 days”, then this action finishes, and the message will be sent as soon as it is needed. If this message is not an automated one, then you have to use the createCampaign method to send your message.

If you want to send another email to the recipients of the same list, then you must request using the createEmailMessage / createSmsMessage method and continue as in the previous paragraph.

if it is not necessary to change the text of the letter, and if you need to re-send the same email to the same list again, you can use the createCampaign method with the same message_id again.

After sending, you can get the statistics by requesting the getCampaignDeliveryStats method.

Quick start

We have prepared the libraries for popular programming languages and distribute them for free, so you can quickly add the possibility of sending of the emails into your web project. There are classes for PHP.