API for SMS Campaigns

Unisender API is a special interface for developers that allows you to integrate the features of a campaign with a web service or desktop application.

Our API for SMS campaigns allows you to manage your contact lists, create and send SMS campaigns, and analyze the statistics. Besides, methods for cooperation with partners are available to you.

API is free for all types of accounts. To get access to API for SMS campaigns, you will need the key that can be found in your account.

 

You should not give your key to other persons, or make it visible in the web page code to secure yourself from having your company’s name used for someone else’s SMS campaigns.

How to use API

Call method

API methods call for SMS campaigns means an HTTPS request to URL in the form of:

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

where:

LANG * is the language of API server messages (currently, supporting only ru, en, ua)
METHOD * is the name of the method
KEY * API access key
ARG_1 ... ARG_N method arguments (different for each method)

All parameters should be encoded in UTF-8. In the example above the parameters are given in the GET request, but you can send them through POST request as well. We recommend that you send the api_key parameter only through POST to ensure it’s not saved in proxy servers logs.

The response gets back in the form of a JSON object. Both the request and the response can be compressed with gzip or bzip2 algorithms.

Successful method call

If the call is successful, the object will include the “result” field (its content depends on the method called) and won’t include the “error” field.

The successful method call can include the “warnings” field, which contains an array of warning objects with the only “warning” string field.

An example of a successful method call:

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

Unsuccessful method call

If an error occurred while executing the method, the response will contain the “error” field with an HTML message of the error and the “code” field with the error code.

An example of a response with an error:

{
    "code": "invalid_arg",
    "error": "fields: This value \"mymail@@@@mail.ru\" is not a valid email address.",
    "result": ""
}

Major error codes while working with API

List of available methods for SMS creation and sending

Work with contact lists
Create and send messages
Get the statistics
Work with additional fields and tags
Methods for partner websites

Work with contact lists:

  • getLists — get the lists for campaigns with their codes;
  • createList — create a new campaign list;
  • updateList — change the properties of the campaign list;
  • deleteList — delete the campaign list;
  • subscribe — subscribe the recipient to one or several campaign lists;
  • exclude — exclude the recipient from campaign lists;
  • unsubscribe — unsubscribe the recipient from the campaign;
  • importContacts — mass import and synchronization of contacts;
  • exportContacts — export of contacts’ data;
  • getTotalContactsCount — get the information on the total number of the contacts;
  • getContactCount — get the number of contacts in the list;
  • getContact — get the information on one contact.

Create and send messages:

Get the statistics:

Work with additional fields and tags:

Methods for partner websites:

  • validateSender — confirm the sender address;
  • register — register the user (for partner websites);
  • checkUserExists — check if the user exists by their login or email;
  • getUserInfo — get the information on the user (for partner websites);
  • getUsers — get the information on the users (for partner websites);
  • transferMoney — transfer money to the user’s balance (for partner websites);
  • getAvailableTariffs — get the list of available plans (for partner websites);
  • changeTariff — switch the user plan (for partner websites);
  • setSenderDomain — get the DKIM key for the sender domain.

How to call methods

The steps to follow when calling a method for SMS campaigns.

You can have one or several contact lists. Before sending an SMS to a list, learn the list code in the service by calling “getLists” or create a new list by calling “createList”.

Add contacts to the list by calling “importContacts” (it will add them all at once) or by calling “subscribe” (it will add them one by one).

Now you are ready to send messages. You can create a campaign by calling “createSmsMessage”. Make sure you state the recipient list id that contains phone numbers. In this case, your message will be sent to all subscribers from the list, which were active at the moment you called “createSmsMessage”.

It’s time to send your SMS campaign. Call “createCampaign” method to do it. State the message_id that you received after you called “createSmsMessage”. You can send your campaign once it’s created or schedule it.

If you want to send another SMS to the same list, call ”crеateSmsMessage” again and follow the steps above.

The chain createSmsMessage -> createCampaign sends an SMS campaign to the list. You can send separate SMS as well by calling “sendSms”, and check the delivery status by calling “checkSms”.

After your SMS campaign has been sent, you can learn the results by calling “getCampaignDeliveryStats”.

Quick start

We have created a PHP class library to help you quickly add a feature of sending SMS campaigns to your web project.

To configure the API, you can use our guidelines to create integration.

Did we answer to your question?

0
0