API Documentation

  2. Home
  4. Docs
  6. API Documentation
  8. Active APIs
  10. addSubscribers

addSubscribers

Adds subscribers to a list in your Juvlon account.

You can add upto 100,000 subscribers along with personalizations like first name, last name, etc. (subscriber data that you may want to use in your emails to your subscribers) in each API call.

You need to mandatorily 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 inactivated and why, etc.

Subscribers with email addresses as follows will be inactivated:

•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 the new subscriber added to the list will also be inactivated.
•Email address with a bad domain – Juvlon does not send out emails to certain bad domains (for e.g. spamtrap domains, temporary domains etc.). If you send out an email to any such domain, your entire sending might get considered as spamming by spamming agencies like Spamhaus and UriBl resulting in soft bounces or in your emails reaching your subscribers’ Spam / Junk folders. Hence, Juvlon performs checks as soon as you add subscribers, and if the domain of any email address matches any of these bad domains, then the subscriber is inactivated.

Similarly, any invalid mobile number provided will also be inactivated so that no attempt to send an SMS message to these numbers will be made.

Please note that a subscriber whose email address has been inactivated (due to any of the reasons described above) will continue to receive SMS messages from Juvlon as long as his mobile number is valid. Similarly, a subscriber inactivated for an invalid mobile number will continue to receive emails from Juvlon if his 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",
   "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",
    "customField":"$customField"
     },{
     "prefix":"$prefix",
     "firstName":"$firstName",
     "middleName":"$middleName",
     "lastName":"$lastName",
     "email":"$email",
     "mobile":"$mobile",
     "customField":"$customField"
      }]
      }';

Arguments

NameTypeDescriptionDefault
ApiKeyStringMandatory. The apiKey that gives you access to our HTTP APIs.
The apiKey authenticates you and helps us to identify your Juvlon account.		 
listNameStringThe 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
isUniqueIntSpecify 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		 
subscribersStructureMandatory. 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 { }. 
emailStringThe 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.		 
mobileStringThe mobile number of the subscriber to send SMS messages to.
It is mandatory to provide either the email address or the mobile number of a subscriber.		 
prefixStringThe prefix / title of the subscriber. E.g. Mr., Mrs., Dr. etc..To be used as a personalization in your email / SMS messages. 
firstNameStringThe first name of the subscriber. To be used as a personalization in your email / SMS messages. 
middleNameStringThe middle name of the subscriber. To be used as a personalization in your email / SMS messages. 
lastnameStringThe last name of the subscriber. To be used as a personalization in your email / SMS messages. 
transactionalOnlyInt• 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.		 
phoneStringThe primary telephone of the subscriber. To be used as a personalization in your email / SMS messages. 
addressStringThe residential address of the subscriber. To be used as a personalization in your email / SMS messages. 
cityStringThe city in which the subscriber resides. To be used as a personalization in your email / SMS messages. 
stateStringThe state in which the subscriber resides. To be used as a personalization in your email / SMS messages. 
pincodeStringThe pin code of the subscriber’s residential address. To be used as a personalization in your email / SMS messages. 
countryStringThe Country where the subscriber resides. To be used as a personalization in your email / SMS messages. 
residencePhoneStringThe residence phone number of the subscriber. To be used as a personalization in your email / SMS messages. 
designationStringThe official designation of the subscriber. To be used as a personalization in your email / SMS messages. 
companyStringThe company in which the subscriber works. To be used as a personalization in your email / SMS messages. 
companyAddressStringThe company address where the subscriber works. To be used as a personalization in your email / SMS messages. 
companyCityStringThe city where the subscriber works. To be used as a personalization in your email / SMS messages. 
companyStateStringThe state where the subscriber works. To be used as a personalization in your email / SMS messages. 
companyCountryStringThe Country where the subscriber works. To be used as a personalization in your email / SMS messages. 
companyPinStringThe pin code of the area where the subscriber works. To be used as a personalization in your email / SMS messages. 
companyphoneStringThe office phone number of the subscriber. To be used as a personalization in your email / SMS messages. 
companyFaxStringThe office fax number of the subscriber. To be used as a personalization in your email / SMS messages. 
birthdayStringThe subscriber’s birthday in ‘yyyy-mm-dd’ format. Can be used to trigger emails on the subscriber’s birthday or as a personalization in emails / SMS. 
anniversaryStringThe subscriber’s anniversary date in ‘yyyy-mm-dd’ format. Can be used to trigger emails on the subscriber’s anniversary day or as a personalization in emails / SMS. 
referenceNoStringAny reference number that you want to use for the subscriber. To be used as a personalization in your email / SMS messages. 
extra1StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
extra2StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
extra3StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
extra4StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
extra5StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
extra6StringAny extra information that you may like to store about the subscriber. To be used as a personalization in your email / SMS messages. 
sourceStringWhere you sourced your subscriber from. This can be used for segmentation purposes. 
customFieldStringCustomized text for your internal tracking. 

Return value

TypeDescription
codeThe Success or Error response code as returned by the API. Please refer to the section “Possible-Response-Codes” for more details. 
statusDescription of the error code returned. 
transactionIdA 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",
          "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",
            "customField":"custom_text_1"
          },{
            "prefix":"Mr.",
            "firstName":"Mark",
            "middleName":"Q",
            "lastName":"Twain",
            "email":"example2@abc.com",
            "mobile":"9890999992",
            "customField":"custom_text_2"
            }]
         }'; 
$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",
     "subid":"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