API for SMS Campaigns

Selzy 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.selzy.com/LANG/api/METHOD?format=json&api_key=KEY&arg1=ARG_1&argN=ARG_N

where:

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@@@@gmail.com\" 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:

• createSmsMessage — create an SMS for a campaign;
• createCampaign — schedule SMS messages;
• cancelCampaign — cancel the scheduled campaign;
• sendSms — send an SMS;
• checkSms — check the SMS delivery status;
• deleteMessage — delete the message.

Get the statistics:

• getCampaignDeliveryStats — get the delivery status report for the given SMS campaign;
• getCampaignCommonStats — get the general information on the delivery for the given SMS campaign;
• getVisitedLinks — get the link clicks statistics;
• getCampaigns — get the campaign list;
• getCampaignStatus — get the SMS campaign status;
• getMessages — get the message list;
• getMessage — get the information on the SMS;
• listMessages — get the list of messages without a body and attachments.

Work with additional fields and tags:

• getFields — get the list of user fields;
• createField — create a new field;
• updateField — change the parameters of the field;
• deleteField — delete the field;
• getTags — get the list of user tags;
• deleteTag — delete the tag.

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

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.