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.
Result of a successful method call
If the call is successful, the object will contain the «result» field, the content of which depends on the method called and will not contain the «error» field. But even if the method has been executed successfully, there may be a «warning» field containing an array of warning objects with the only «warning» string field.
Example of a successful method call:
{
"result":{
"message_id":34423432
},
"warnings":[
{"warning":"probably not a mobile phone"}
]
}
Result of an unsuccessful method call
An indicator of an error in executing the method is the presence of the “error” field with an HTML error message in the response object. In addition, the response object will also contain a “code” field with the string error code in case of an error. In case of an error, the «result» field should be ignored.
List of methods
- Working with contact lists
- Working with additional fields and tags
- Creating and sending messages
- Working with templates
- Obtaining statistics
- Methods for partner sites
- getLists — get mailing lists with their codes
- createList — create a new mailing list
- updateList — change mailing list properties
- deleteList — delete the mailing list
- subscribe — subscribe the mail recipient to one or more mailing lists
- exclude — exclude the mail recipient from the mailing lists
- unsubscribe — unsubscribe the mail recipient from mailing list
- importContacts — bulk import and synchronization of contacts
- exportContacts — export contacts data
- getTotalContactsCount — get the number of contacts
- getContactCount — get the number of contacts in the list
- getContact – get information about a contact
Working with additional fields and tags
- getFields — get the list of user fields
- createField — create a new field
- updateField — change field parameters
- deleteField — delete a field
- getTags — get the list of user tags
- deleteTag — delete a tag
- createEmailMessage — create an email for a mailing campaign
- createSmsMessage — create SMS for a campaign
- createCampaign — schedule an email or SMS campaign
- cancelCampaign — cancel a previously scheduled campaign
- getActualMessageVersion — get the actual version of the message
- sendSms — send the SMS message
- checkSms — check SMS delivery status
- sendEmail — simplified sending of individual emails
- sendTestEmail — sending test emails (to own email address)
- checkEmail — check email delivery status
- updateOptInEmail — change the text of the message with the subscription confirmation link
- getWebVersion — get a link to the web version of the message sent
- deleteMessage — delete the message
- updateEmailMessage — edit the email for a mailing campaign
- createEmailTemplate — create a message template for a mailing campaign
- updateEmailTemplate — edit the existing message template
- deleteTemplate — delete the template
- getTemplate — get template information
- getTemplates — get the list of all templates created in the system
- listTemplates — get the list of all templates without a body
- getCampaignDeliveryStats — get the report on the message delivery status for a given mailing campaign
- getCampaignCommonStats — get general information on the delivery results for a given mailing campaign
- getVisitedLinks — get the click-through statistics
- getCampaigns — get the list of mailing campaigns
- getCampaignStatus — get the mailing campaign status
- getMessages — get the list of messages
- getMessage — get information about SMS or email message
- listMessages — get the list of messages without body and attachments
- getCheckedEmail — get the list of confirmed/unconfirmed emails
- validateSender — confirm the return address
- register — register the user (for partner sites)
- checkUserExists — check existence of the user by login or email
- getUserInfo — get user information (for partner sites)
- getUsers — get information about users (for partner sites)
- transferMoney — transfer money to user’s account (for partner sites)
- getPayments — get the list of payments made by the user (for partner sites)
- getAvailableTariffs — the method to get the list of tariffs (for partner sites)
- changeTariff — switch the user to other tariff (for partner sites)
- setSenderDomain — get the DKIM key for sender’s domain
System Event Notification — Webhooks
To address the task of notifying about changes in the delivery status, we have made a new API that will give you the opportunity to register and manage notifications handlers, the so-called Webhooks.
Please find a detailed article here.
The procedure of methods calls
You can have one or several lists — it is assumed that each list corresponds to a specific campaign topic, and the email recipient can be subscribed to one list and not be subscribed to another one.
Then, you can send messages. Create a message using the createEmailMessage (or createSmsMessage) method. When doing this, you specify the id of the list with email recipients — and the email will be addressed to all email recipients from these lists that are active at the time of calling createEmailMessage / createSmsMessage method. If this is an automatically sent message such as “Step by Step Slimming in 10 Days” or something similar, this will be the last action, and the message will be sent as soon as you need. If this is not a serial message, you need to call the createCampaign method to send the created message.
If you need to send another message on the same list, call createEmailMessage / createSmsMessage again and continue with the actions described in the previous paragraph.
If you do not need to change the text of the message, but you need to send the same message again on the same list, you can call createCampaign again with the same message_id.
After completion of the campaign, you can get the sending results using the getCampaignDeliveryStats method.
Quick start
We have prepared a library for the PHP class so that you can quickly add the possibility of guaranteed sending messages to your web project, as well as basic guidelines to create integrations.