Adds subscribers to a list in your Juvlon account.
You can add up to 100,000 subscribers in each API call, along with personalizations like first name, last name, etc. (subscriber data that you may want to use in your emails to your subscribers).
You must provide either an email address or a mobile number for each subscriber. If neither is provided, then the subscriber will not be added to the list.
Some of the subscribers that you provide may already exist in your Juvlon account (in the same list or another list). You can choose how you wish to add them to your list:
| • | Update the personalization fields of the already existing subscriber with the data provided in this API call, and add him/her to the current list as well as in the old list(s). No subscriber credit will be deducted in this case as no new subscriber is added. |
| • | Make a new entry for every subscriber even if it already exists. You may need this option if you have 2 personalization data for a subscriber. For e.g. the same subscriber with 2 residential addresses, or the same subscriber with 2 policies. Subscriber credit will be deducted for every new entry. |
When all the subscribers are added to your list, you will receive an email notification from Juvlon with a detailed summary of how many subscribers were added, how many subscribers were not added and why, etc.
Subscribers with email addresses as follows will not be added:
| • | Invalid email address (e.g. “john.gmail.com”, or “john@gmail”) |
| • | Already Inactivated email address – if the subscriber was already present in your account and was inactive for any reason (for e.g., the subscriber has unsubscribed from receiving emails from you), then any attempt to add that subscriber (same email address) to the same or another list will fail. |
| • | Email address with a bad domain – Juvlon does not send out emails to certain bad domains (for e.g. spamtrap domains, temporary domains etc.). |
Similarly, any invalid mobile number provided will also not be added so that no attempt to send an SMS message to these numbers is made.
Please note that a subscriber’s email address and/or mobile number can be inactivated if the subscriber chooses to unsubscribe. In such cases, a subscriber, whose email address has been inactivated, will continue to receive SMS messages from Juvlon as long as their mobile number is active. Similarly, a subscriber with an inactivated mobile number will continue to receive emails from Juvlon if their email address is active.
This API needs to be called using an HTTP Post method with data in JSON format as shown below.
URL: https://api2.juvlon.com/v4/addSubscribers
Json Parameter - '{"apiKey":"$apiKey",
"listName":"$listName",
"isUnique":"$isUnique",
"sendReport":"Yes",
"customField":"$customField",
"subscribers":[
{
"prefix":"$prefix",
"firstName":"$firstName",
"middleName":"$middleName",
"lastName":"$lastName",
"email":"$email",
"transactionalOnly":"$transactionalOnly",
"mobile":"$mobile",
"phone":"$phone",
"address":"$address",
"city":"$city",
"state":"$state",
"pinCode":"$pinCode",
"country":"$country",
"residencePhone":"$residencePhone",
"designation":"$designation",
"company":"$company",
"companyAddress":"$companyAddress",
"companyCity":"$companyCity",
"companyState":"$companyState",
"companyCountry":"$companyCountry",
"companyPin":"$companyPin",
"companyPhone":"$companyPhone",
"companyFax":"$companyFax",
"birthday":"$birthday",
"anniversary":"$anniversary",
"referenceNo":"$referenceNo",
"extra1":"$extra1",
"extra2":"$extra2",
"extra3":"$extra3",
"extra4":"$extra4",
"extra5":"$extra5",
"extra6":"$extra6",
"source":"$source"
},{
"prefix":"$prefix",
"firstName":"$firstName",
"middleName":"$middleName",
"lastName":"$lastName",
"email":"$email",
"mobile":"$mobile"
}
]
}
Arguments
| Name | Type | Description | Default |
|---|---|---|---|
| ApiKey | String | Mandatory. The apiKey that gives you access to our HTTP APIs. The apiKey authenticates you and helps us to identify your Juvlon account. | |
| listName | String | The name of the list to which the subscribers should be added. • If no list with the name provided exists, then a new list with that name is created. • If no list name is provided, then the subscriber gets added to the default list. | API_EMAILS |
| isUnique | Int | Specify how you wish to add your subscribers if they already exist in your Juvlon account: • Set to “1” (default) for updating the personalization fields of the already existing subscriber with the data provided in this API call, and adding him/her to the current list as well as in the old list(s). • Set to “0” for adding a new entry for every subscriber even if it already exists. You may need this option if you have 2 personalization data for a subscriber. For e.g. the same subscriber with 2 residential addresses, or the same subscriber with 2 policies | 1 |
| sendReport | String | Specify if you need an Email notification which provides a summary report of adding/updating subscribers. Notification is sent to the registered email address of the Juvlon account. • Set as “Yes” (default) for receiving the Email notification. • Set as “No” to not send an Email notification. | Yes |
| customField | String | Custom text per API call for your own identification/tracking. This field, if passed in an API call, will be provided back to you in a webhook which provides the API log for each call. | |
| subscribers | Structure | Mandatory. A list / array of subscribers to be added. The list should be provided within square braces [ ], and each subscriber’s details should be provided within curly braces { }. | |
| String | The email address of the subscriber to send emails to. It is mandatory to provide either the email address or the mobile number of a subscriber. | ||
| mobile | String | The mobile number of the subscriber to send messages. It is mandatory to provide either the email address or the mobile number of a subscriber. | |
| prefix | String | The prefix / title of the subscriber. E.g. Mr., Mrs., Dr. etc.. | |
| firstName | String | The first name of the subscriber. | |
| middleName | String | The middle name of the subscriber. | |
| lastName | String | The last name of the subscriber. | |
| transactionalOnly | Int | • Set to “0” (default) if the subscriber should be sent promotional as well as transactional emails, • Set to “1” if the subscriber should be sent transactional emails only. | 0 |
| phone | String | The primary telephone of the subscriber. | |
| address | String | The residential address of the subscriber. | |
| city | String | The city in which the subscriber resides. | |
| state | String | The state in which the subscriber resides. | |
| pinCode | String | The pin code of the subscriber’s residential address. | |
| country | String | The Country where the subscriber resides. | |
| residencePhone | String | The residence phone number of the subscriber. | |
| designation | String | The official designation of the subscriber. | |
| company | String | The company in which the subscriber works. | |
| companyAddress | String | The company address where the subscriber works. | |
| companyCity | String | The city where the subscriber works. | |
| companyState | String | The state where the subscriber works. | |
| companyCountry | String | The Country where the subscriber works. | |
| companyPin | String | The pin code of the area where the subscriber works. | |
| companyPhone | String | The office phone number of the subscriber. | |
| companyFax | String | The office fax number of the subscriber. | |
| birthday | String | The subscriber’s birthday in ‘yyyy-mm-dd’ format. Can be used to trigger emails on the subscriber’s birthday. | |
| anniversary | String | The subscriber’s anniversary date in ‘yyyy-mm-dd’ format. Can be used to trigger emails on the subscriber’s anniversary day. | |
| referenceNo | String | Any reference number that you want to use for the subscriber. | |
| extra1 | String | Any extra information that you may like to store about the subscriber. | |
| extra2 | String | Any extra information that you may like to store about the subscriber. | |
| extra3 | String | Any extra information that you may like to store about the subscriber. | |
| extra4 | String | Any extra information that you may like to store about the subscriber. | |
| extra5 | String | Any extra information that you may like to store about the subscriber. | |
| extra6 | String | Any extra information that you may like to store about the subscriber. | |
| source | String | Where you sourced your subscriber from. This can be used for segmentation purposes. |
Return value
| Name | Type | Description | |
|---|---|---|---|
| code | String | The Success or Error response code as returned by the API. Please refer to the section “Possible-Response-Codes” for more details. | |
| status | String | Description of the error code returned. | |
| transactionId | String | A number generated by the API to uniquely identify the current call. Also known as the API_Call_ID. |
Usage / Example(s)
PHP Example Code for Integration
$url = 'https://api2.juvlon.com/v4/addSubscribers';
$data = '{"apiKey":"KEY",
"listName":"ListABC",
"isUnique":"0",
"sendReport":"Yes",
"customField":"custom_text_for_this_call",
"subscribers":[
{
"prefix":"Mr.",
"firstName":"John",
"middleName":"K",
"lastName":"Smith",
"email":"example1@abc.com",
"transactionalOnly":"0"
"mobile":"9890999991",
"phone":"+91227492682648",
"address":"House 5, Suncity",
"city":"Mumbai",
"state":"Maharashtra",
"pinCode":"9604",
"country":"India",
"residencePhone":"912274926829",
"designation":"Project Manager",
"company":"XYZ ltd.",
"companyAddress":"Office no 5, ABC IT Park",
"companyCity":"Mumbai",
"companyState":"Maharashtra",
"companyCountry":"India",
"companyPin":"9607",
"companyPhone":"+912274926826",
"companyFax":"+912274926827",
"birthday":"1988-06-10",
"anniversary":"2015-06-11",
"referenceNo":"123",
"extra1":"98732",
"extra2":"989",
"extra3":"7687",
"extra4":"989",
"extra5":"7687",
"extra6":"K987JF",
"source":"SalesForce"
},{
"prefix":"Mr.",
"firstName":"Mark",
"middleName":"Q",
"lastName":"Twain",
"email":"example2@abc.com",
"mobile":"9890999992"
}]
}';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$res1 = curl_exec($ch);
curl_close($ch);
Success-Response
HTTP/1.1
{
"code":200,
"status":"Success",
"transactionId":327
}
Error-Response
HTTP/1.1
{
"code":403,
"status":"Error"
}
Possible-Response-Codes
200 Success: API Request Accepted
401 Error: Invalid Method
402 Error: Unauthorized/Empty Key
403 Error: Unauthorized/Invalid Key
405 Error: Your Juvlon account has expired
448 Error: Your Juvlon account is Deactivated
602 Error: No subscriber provided
444 Error: Low Subscriber credit
470 Error: Exceeded 1 Lac subscribers (maximum allowed per call)
441 Error: Invalid list name
471 Error: Invalid isUnique