This method adds contacts (email address and/or mobile phone numbers) of the contact to one or several lists, and also allows you to add/change values of additional fields and tags.
By default, an email with a request to confirm the subscription is sent to the contact, but if you have already checked the existence of the address on your own, you can disable this functionality by setting the double_optin parameter.
Depending on the value of the double_optin parameter, the contact will either receive a «new» status, or an email with a request to confirm the subscription will be sent and it will receive the «confirmation requested» status, or an error message will be returned (see more details about the statuses).
If you need to check whether the contact is in the list or account, you can call the exportContacts method and transfer the address of the selected contact in the email parameter.
In order to add a contact without sending a letter, you need to use the double_optin = 3 parameter
Principle of use
| Syntax and URL to call the method |
| subscribe (string list_ids, string array fields [string tags, int double_optin, int overwrite]) |
| https://api.selzy.com/en/api/subscribe?format=json&api_key=KEY& list_ids=134,135&fields[email][email protected]&tags=MyTag1, MyTag2&double_optin=0&overwrite=0 |
| Arguments | |
| api_key * | API access key |
| list_ids * | List codes separated by comma in which a contact is to be added. Codes can be obtained by calling the getLists method. They match the codes used in the subscription from. Examples:
list_ids=123456 list_ids=123456,345678,2344423 |
| fields * | Associative array of additional fields. The array in the request is transferred as a string in the form fields[NAME1]=VALUE1&fields[NAME2]=VALUE2. There must be at least the «email» or «phone» field, otherwise the method will return an error. In the case there are both email and phone number, the contact will be included in the email and SMS campaign lists. Pay attention that «phone» field value should be passed in the international phone number format (e.g. +79261232323)
Examples: fields[email][email protected] fields[email][email protected]&fields[Name]=UserName |
| tags | Tags separated by commas that are added to the contact. Allowed number of tags is 10. |
| double_optin | It obtains the value of 0, 3, or 4.
|
| overwrite | Field and tag rewriting mode, the number from 0 to 2 (0 by default). It sets what needs to be done in case of existence of a contact (the contact is identified by the email address and/or phone number).
If 0, only new fields and tags are added, the existing fields retain their value. If 1, all old fields are deleted and replaced with new ones, all old tags are also deleted and replaced with new ones. |
| Return value |
Object with the single person_id field – a positive integer decimal 64-bit unique contact code.Example of the return value:
{"result":{"person_id":2500767342}}
|
Examples of forming the URL request
https://api.selzy.com/en/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email][email protected]&fields[Name]=John+Doe
— add a new contact with the name John Doe and the address [email protected] to the list with code 555777. Immediately after been added, he will be sent a request to confirm that he really agrees to receive mailings.
https://api.selzy.com/en/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]= [email protected]&fields[Name]=John+Doe&double_optin=0&tags=RedRoseCustomer
— add a new contact with the name John Doe and the address [email protected] to the list with code 555777. The contact will be assigned the RedRoseCustomer tag for the purposes of further campaign segmentation. Confirmation request will not be sent, the address will be signed automatically.
Resubscription
If you add email and phone number of the contact, which is already present in your personal account, there may be the following cases:
- when a request is sent, the email is the same, but the phone number is different. The phone number will be replaced with the new one, provided that it does not belong to another contact in your personal account;
- when a request is sent, the phone number is the same, but the email is different. The email will be replaced with the new one, provided that it does not belong to another contact in your personal account.
Otherwise, you will get an error similar to the following:
{
"error": "Contacts [email protected] and +77777777 already exist but owned
by different subscribers",
"code": "unspecified",
"result": [
]
}