It is a method of bulk import of contacts. It can also be used for recurring synchronization with the contact database stored on your own server (see also the description of the exportContacts method). You can import data of no more than 500 contacts per call. Larger lists should be imported in several calls (this restriction is due to the limitations of the POST request).
If there are new email addresses among the subscribed ones, they receive the «new» status by default.
Technical limitations: the maximum number of user fields is 50. The timeout for one call is 30 seconds from the moment the request is sent to the server. If no response has been received after the timeout expires, we recommend you to make up to two more attempts, and contact the support if there is no answer.
When you import a contact list from a file, bulk copy-and-paste contacts, or use the API method importContacts, Selzy checks the contacts for spam-traps, technical and role-based addresses.
For example, addresses like info@, sales@, no-reply@, or all@ will be recognized as potentially dangerous. They negatively impact the deliverability of your emails and both your sender and domain reputation: since such addresses don’t belong to individual users, the risks of email bounces and spam complaints are much higher.
Potentially dangerous email addresses will not be imported. You can find more information about them in the import error report.
If you want to send campaigns to role-based addresses, use Double Opt-In.
Principle of use
| Syntax and URL to call the method |
| importContacts (string array field_names, string array data [bool overwrite_tags, bool overwrite_lists]) |
| https://api.selzy.com/en/api/importContacts?format=json&api_key=KEY&field_names[0]=email ... field_names[N]=MyFieldN&data[0][0][email protected].... &data[N][0][email protected]&overwrite_tags=X&overwrite_lists=X |
| Arguments | |||||||||||||||||||||||
| api_key * | API access key | ||||||||||||||||||||||
| field_names * | Array of data column names. There must be at least the «email» or «phone» field, otherwise the method will return an error. The names of the existing user fields and the names of the following system fields can be specified:
|
||||||||||||||||||||||
| data * | Array of contact data, where each element is an array of fields in the order the field_names follow. An example for two contacts (the email address is included in the 123 list in the first one, and it is outside the lists in the second one):
field_names[0]=email&field_names[1]=email_list_ids& data[0][0][email protected]&data[0][1]=123&data[1][0][email protected] |
||||||||||||||||||||||
| overwrite_tags | Optional logical field (0 or 1, the default value is 0). It shows whether tags are overwritten (if 1), or only the new ones are added without deleting the old ones (if 0). | ||||||||||||||||||||||
| overwrite_lists | Optional logical field (0 or 1, the default value is 0).
1 means to replace all the data about when and in which lists contacts are included and from which contacts are excluded with new data. I.e., if the contact is now included in three lists and only one is indicated in the email_list_ids, the contact will be included in only one specified after the call, and the time of the subscription will be the one specified in email_subscribe_times (or the current one if the email_subscribe_times field has been skipped). |
||||||||||||||||||||||
| Return value | |||||||||
| JSON object with the following fields: | |||||||||
| total | Integer decimal non-negative number — the total number of contacts in the input data array. Amount inserted + updated + deleted may be less than the total if there were errors or duplicates. | ||||||||
| inserted | Integer decimal non-negative number — the number of successfully added contacts, none of which is duplicated. | ||||||||
| updated | Integer decimal non-negative number — the amount of the updated contact data (email or phone numbers that have already been present in the database). | ||||||||
| deleted | Integer decimal non-negative number — the number of successfully deleted contacts, both new and existing ones, as well as successfully deleted contacts. | ||||||||
| new_emails | Integer decimal non-negative number less than or equal to the total. Number of the imported email addresses that have received the «new» status. This number includes the previously existing addresses, the status of which was «new». | ||||||||
| invalid | Integer decimal non-negative number greater than or equal to zero. The number email addresses that have been imported. | ||||||||
| log | Array of errors and import warnings, each element is an object with the following properties:
|
||||||||
Example of the return value:
{
"result":{
"total":4, "inserted":2, "updated":1, "deleted":2, "new_emails":1, "invalid":2,
"log":[
{"index":0,"code":"e_email_invalid",
"message":"Invalid email format"},
{"index":2,"code":"e_phone_not_unique",
"message":"Duplicate telephone number"}
]
}
}
If while importing the limit on the number of contacts within the current plan is exceeded, the response will be returned with a warning: {
"result":{
"total":1, "inserted":1, "updated":0, "deleted":0, "new_emails":1, "invalid":0,
"log":[
{"index":0,"code":"w_common_overlimit",
"message":"The number of contacts for the current tariff plan has been exceeded (but the string has been added)"
}
]
},
"warnings":[
{
"warning":"Addresses overlimit for current period"
}
]
}
If role-based or technical addresses are detected during the import process, the response will be as follows: {
"result":{
"total":1, "inserted":0, "updated":0, "deleted":0, "new_emails":0, "invalid":1,"role_based": 1,
"log":[
{"index":0,"code":"w_common_overlimit",
"message":"Error (email was ignored). Role-based or technical email address:
\"[email protected]\""
}
]
}
}
|
|||||||||
Examples of creating a URL request
https://api.selzy.com/en/api/importContacts?format=json&api_key=KEY& field_names[0]=email&field_names[1]=Name&field_names[2]=email_list_ids& data[0][0][email protected]&data[0][1]=Anna&data[0][2]=778899& data[1][0][email protected]&data[1][1]=Kate&data[1][2]=778899& data[2][0][email protected]&data[2][1]=John&data[2][2]=778899& data[3][0][email protected]&data[3][1]=Mike&data[3][2]=778899& data[4][0][email protected]&data[4][1]=Bill&data[4][2]=778899
— add 5 new contacts with addresses 1 .. [email protected] with the names Anna, Kate, John, Mike and Bill to list with the code 778899. Please note, that it is more correct to make requests via POST as the allowable length of a request is substantially less in a GET request.
