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

exportContacts method

Вы здесь:

Export of contact data from UniSender. There are various scenarios to use this method:

  • Backup.
  • You can download the entire contact database with the information as detailed as possible.
  • Synchronization with data of your server.
  • Suppose that you always add new contacts firstly to your server and then to UniSender. The contact can unsubscribe through UniSender, or you can delete it on your server. In order to synchronize, you need to upload only email addresses (or phone numbers) of contacts through exportContacts and check if there are any contacts deleted from your server. Then, using importContacts, you import new contacts, change data of the modified ones, and delete those contacts that have been deleted on your server.

The maximum volume of data exported per call is limited, therefore, in the event there is a large number of contacts, you should unload them piece by piece (not more than 1000 records at a time) using the offset and limit arguments.

Principle of use

Syntax and URL to call the method
exportContacts (int list_id, string array field_names, int offset, int limit, string tag, string email,
string email_status, string phone, string phone_status).
https://api.unisender.com/ru/api/exportContacts?format=json&api_key=KEY
&list_id=134&field_names[]=email&field_names[]=email_status&tag=TAG
&email=EMAIL&email_status=EMAIL_STATUS&phone=PHONE&phone_status
=PHONE_STATUS
Arguments
api_key * API access key.
list_id Optional export list code. If it is not specified, all lists will be exported. Codes of the lists can be obtained by calling the getLists method.Warning: if the list is specified, those email addresses that are not included in the list, but contacts have phone numbers included in this list, will be included in the upload result as well.
field_names Array of field names to be exported. If it is absent, all possible fields are exported.
email Email address. If this parameter is specified, the result will contain only one contact with such email address.
phone Phone number. If this parameter is specified, the result will contain only one contact with such phone number.
tag Tag. If this parameter is specified, the search will take into account only contacts that have such tag.
email_status Email address status. If this parameter is specified, the result will contain only one contact with such email address status. The valid values are listed in the list of system fields below.
phone_status Phone number status. If this parameter is specified, the result will contain only one contact with such phone number status. The valid values are listed in the list of system fields below.
limit Positive integer — the number of contacts being exported. The maximum possible value, which is also the default value, is 1000.
offset Non-negative integer — the number of the first exported contact. If it is not specified, the export is performed from the beginning by default, and the offset is considered to be zero. When you export large lists, you are recommended to make several calls in portions of one thousand contacts. See also the following limit argument.
Return value
JSON object with the following fields:
field_names Array of data field names. The names of the system fields do not depend on the language, the names of the user fields are taken from the substitution names.

The list of system fields:
tags List of tags separated by commas.
email Contact’s email address.
email_status Email address status. Possible field values during export:

  • new — new.
  • invited — an invitation was sent with a subscription confirmation link, we are waiting for a response, it is not possible to send any messages to this address yet.
  • active — active address, mailing is possible.
  • inactive — the address is excluded through the web interface, no mailings are possible, but can be included again through the web interface.
  • unsubscribed — the recipient has unsubscribed from all campaigns.
  • blocked — the address is blocked by the administration of our service (for example, based on a complaint of the recipient), it is not possible to send any messages to this address. It can be unlocked only at the request of the recipient.
  • activation_requested — activation of the address is requested from the UniSender administration, t is not possible to send any messages to this address yet..
email_availability Availability of the email address based on the results of recent campaigns. Messages will be sent only to available recipients.Possible values:

  • available — address is available;
  • unreachable — address is not available;
  • temp_unreachable — address is temporarily unavailable;
  • mailbox_full — mailbox is full;
  • spam_rejected — the message was considered as spam by the recipient server. This status will be removed in a couple of days;
  • spam_folder — the letter was placed into the spam folder by the recipient.
email_add_time Time when the email address was added, in the «YYYY-MM-DD hh:mm:ss» format, in UTC. If the address was added as a result of a subscription through a form, the time is the same as the time of the subscription request.
email_request_ip IP address from which the subscription request was received. It is 0.0.0.0 for addresses added manually or for which the address is unknown.
email_confirm_time Date and time of the subscription confirmation (click-through to the confirmation link from the letter) in the «YYYY-MM-DD hh:mm:ss» format.
email_confirm_ip IP address from which the subscription request was received. It is 0.0.0.0 for addresses for which the address is unknown.
email_list_ids List codes separated by comma to which the email is subscribed.
email_subscribe_times Dates and time of the list subscription separated by comma, the number and order of dates correspond to the number and order of the list codes in email_list_ids. The dates are in UTC, in the «YYYY-MM-DD hh:mm:ss» format.
email_unsubscribed_list_ids List codes separated by commas into which the -email is included, but has the «unsubscribed» status. These codes are not included in email_list_ids.
phone Contact’s mobile phone.
phone_status Phone status, one of the following:

  • new — new;
  • active — active phone number, mailing is possible. The phone number obtains this status by default when it is added;
  • inactive — the phone number is excluded through the web interface, no mailings are possible, but can be included again through the web interface;
  • unsubscribed — the recipient has unsubscribed from all campaigns;
  • blocked — the recipient is blocked by the administration of our service (for example, based on a complaint of the recipient), it is not possible to send any messages to this address. It can be unlocked only at the request of the recipient.
phone_availability Availability of the phone number based on the results of recent campaigns. SMS will be sent only to available phone numbers. Possible values:

  • available — phone number is available.
  • not_allowed — sending to this phone is not supported by the provider.
  • temp_unreachable — the last sending failed.
  • not_exist —  the phone number does not exist.
phone_add_time Time when the phone number was added, in the «YYYY-MM-DD hh:mm:ss» format, in UTC.
phone_request_ip IP address from which the subscription request was received. It is 0.0.0.0 for addresses added manually or for which the address is unknown.
phone_list_ids, phone_subscribe_times, phone_unsubscribed_list_ids The meaning of the fields matches similar fields for email. Please note that there are no phone_confirm_ip and phone_confirm_time fields for phone numbers.

The request to download the email_list_ids, email_subscribe_times, email_unsubscribed_list_ids and tags fields creates an additional download, so it is better to request only the required fields, rather than to request all and filter the unnecessary ones on your own.

data Two-dimensional data array. Each string corresponds to a single contact.
Response example:

{
  "result":{
    "field_names":[
      "email",
      "Имя",
      "email_status",
      "email_availability",
      "email_subscribed_lists",
      "email_subscribed_times",
      "email_add_time"
    ],
    "data":[
      [
        "test1@example.org",
        "Вася",
        "active",
        "available",
        "123,127",
        "2010-06-15 12:54:07,2010-06-15 12:54:07",
        "2010-06-15 12:34:01"
      ],
      [
        "test2@example.org",
        "Петя",
        "invited",
        "unreachable",
        "123",
        "2010-03-15 18:12:55",
        "2010-03-15 18:12:55"
      ],
      [
        "test3@example.org",
        "Коля",
        "active",
        "avaialable",
        "",
        "",
        "2010-03-15 18:12:55"
      ]
    ]
  }
}

Examples of forming the URL request

https://api.unisender.com/en/api/exportContacts?format=json&api_key=KEY 
— get the data of all contacts (in fact, only the first 1000, 
see the description of the limit parameter)
https://api.unisender.com/en/api/exportContacts?format=json&api_key=KEY&
list_id=222333&field_names[]=Name 
— get only the names of contacts on the list with the code 222333 (in fact, only the first 1000,
see the description of the limit parameter)
https://api.unisender.com/en/api/exportContacts?format=json&api_key=
KEY&list_id=222333 — get data of contacts on the list with the code 
222333 (in fact, only the first 1000, 
see the description of the limit parameter)