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

subscribe method

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.

По умолчанию, на email контакта отправляется письмо с просьбой подтвердить подписку, но если Вы уже проверили существование адреса самостоятельно, то можете отключить это с помощью установки параметра double_optin.

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.unisender.com/en/api/subscribe?format=json&api_key=KEY&
list_ids=134,135&fields[email]=test@example.org&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.Examples:

fields[email]=test@example.org fields[email]=test@example.org&fields[Name]=UserName
tags Tags separated by commas that are added to the contact.
double_optin It obtains the value of 0, 3, or 4.

  • If 0, the contact is considered to only have expressed a desire to subscribe, but has not yet confirmed the subscription. In this case, the contact will be sent an invitation letter to subscribe. The text of the letter will be taken from the properties of the first list from list_ids. By the way, the text can be changed using the updateOptInEmail method or through the web interface.
  • If 3, it is also considered that the contact’s consent has been obtained, and the contact is added with the «new» status.
  • If 4, the system checks the presence of a contact on your lists. If the contact is already present on your lists with the «new» or «active» status, the address will be just added to the list you have specified. If the contact is not present on your lists or its status is other than «new» or «active», an invitation letter to subscribe will be sent to the contact. The text of this letter can be set for each list using the updateOptInEmail method or via the web interface.
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.
If 2, the values of the fields transferred are replaced, and if the existing contact has other fields, they retain their value. In case of transfer of tags, they are overwritten, and if tags are not transferred, the tags retain their old values.

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.unisender.com/en/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]=test@example.org&fields[Name]=John+Doe

— add a new contact with the name John Doe and the address test@example.org 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.unisender.com/en/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]=
test@example.org&fields[Name]=John+Doe&double_optin=0&tags=RedRoseCustomer

— add a new contact with the name John Doe and the address test@example.org 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 test@example.org and +77777777 already exist but owned 
by different subscribers",
  "code": "unspecified",
  "result": [   
  ]
}