API Guide v /11/2013

(1)

API Guide v 1.6| 14/11/2013

(2)

API Guide v 1.6| 14/11/2013

2

About netCORE

netCORE is a leader in digital communications space.

The mission of the company is to help clients communicate effectively for marketing and business needs. We help organizations in the B2C space in acquiring new customers, engaging existing prospects and customers and in delighting top customers. netCORE has pioneered innovative technology-based solutions in mailing & mobility domains. Headquartered in Mumbai, and operating from 8 other locations, netCORE has a pan-India presence.

netCORE has a suite of products and services for digital marketing. It proudly stands at the no.1 position in email marketing and ranks in the top 3 in SMS services in India. Its Email Marketing suite offers access to a scalable technology platform. Mobile marketing solutions range from group SMS based solutions, mobile coupons, sms competitions and polls, integration to back-end systems like ERP, CRM or Loyalty solutions as well as voice solutions on IVR, toll free numbers, missed calls or shortcodes and longcodes for receiving incoming messages.

Its platform also includes a multi-modal response management solution that helps keep track of campaign responses across products. Marketing solutions and services are coupled with an experienced solution selling team that helps ideate on usage of the medium to get the most effective communication.

Its messaging products are one-stop solutions to build the back-end infrastructure in large enterprises as well as small & medium-sized businesses. From Email to VPN, firewall to bandwidth management, virus protection to Spam filtering, netCORE covers it all!

netCORE has an impressive client base of more than 1500 corporates. Its key clients include ICICI Bank, Future Group, Bajaj Allianz, HUL, Colgate, Just Dial, Times Now, Reliance, to name a few.

(3)

API Guide v 1.6| 14/11/2013 3

This document provides a description of the Falconide API version 1.6 available for clients to use the Falconide’s campaign platform for sending Transactional Emails. Falconide helps you focus on your business without the cost and complexity of owning and maintaining an email infrastructure. We manage all of the technical details from scaling the infrastructure to ISP outreach and reputation monitoring to whitelist services and real-time analytics. We offer world class deliverability expertise to make sure your emails get delivered, and handle ISP monitoring, DKIM, domain keys, SPF, feedback loops, whitelabeling, link customization and more.

(5)

API Guide v 1.6| 14/11/2013

5

CHAPTER II:

Falconide Email API

Why Use the API?

Connect Falconide to a CMS, blog platform, e-commerce shopping cart and more for instant sending of transactional mails.

Not A Programmer?

The API is for programmers only. If you’re not a programmer, and there’s not one in your company to bribe, you can contact our Experts.

Get Started

The API uses REST architecture style in which you initiate Key authenticated JSON calls over https.

The general flow for using the API is as follows: 1. Enable API access in Falconide’s panel

2. Submit a request via HTTPS POST to Falconide. We recommend HTTPS POST for best results.

3. Submit a call for each function. You cannot combine multiple calls into a single call. Each API Call is consist of three parts:

1. API URL 2. API Key 3. Input Data

Supported Format for the API Inputs: 1. JSON

(6)

API Guide v 1.6| 14/11/2013

6

2.1 Module: sending

SMTP and HTTP are two methods by which email can be sent to Falconide. After processing, Falconide sends the email to the target via the Internet through SMTP only. This diagram will explain matters:

SMTP is a standard protocol, is relatively simple to implement and send one email per API call. The HTTP API is custom developed by Falconide, is more sophisticated and can send up to 1000 emails per API call.

You can use the HTTP API in cases where the same email needs to be sent to multiple

recipients. Since a single API call can suffice for multiple email addresses, it means a significant saving in bandwidth costs.

2.1.1 HTTP Based API Call:

Sample REST Call:

https://api.falconide.com/falconapi/web.send.rest?api_key=554dgdfgfg5r454345345retet5235 5 &subject=rawurlencode("Weekly statement dated 1st Jan 2013")

&fromname=rawurlencode("Info Stats") &[email protected] &[email protected]

&content=rawurlencode(" Email content here") &[email protected],[email protected] Optional

(7)

API Guide v 1.6| 14/11/2013

7 &footer=1&template=109 (Optional if content provided)

&[email protected] &attachmentid=12,14 &clicktrack=1 &ATT_NAME=rawurlencode(SAC1,SAC2) &ATT_CONTACT=rawurlencode(CON1,CON2) &ATT_ACCOUNTNO=rawurlencode(ACC1,ACC2) &ATT_REGID=rawurlencode(REG1,REG2) &ATT_ADDRESS=rawurlencode(ADD1,ADD2)

Sample JSON Call:

https://api.falconide.com/falconapi/web.send.json?data= { "api_key":"34565475778678678678678678", "email_details":{ "fromname":"Testing%20Falconide", "subject":"Welcome%20to%20our%20falconide%20product", "from":"[email protected]", "replytoid": "[email protected]", "X-APIHEADER": ["ACC123",”SE2532”], "content":"%3Cp%3EDear%20%5BNAME%5D%2C%20%3C%2Fp%3E%3Cp" }, "settings":{ (Optional) "footer":"1", "clicktrack":"1", "opentrack":"1", "unsubscribe":"1", "bcc":"[email protected]", "attachmentid":"1,3,4", "template":"101", }, "recipients":["[email protected]","[email protected]"],

(8)

API Guide v 1.6| 14/11/2013 8 "attributes":{ (Optional) "NAME":["SION1","SION2"], "REGID":["RSION1","RSION2"] } "files": { (Optional) "mdata.pdf": "%3Cp%3EDear%20%EInFO%20Systems%3C%2Fp%3E", "pub.jpg": "%3Cp%3EDear%20%EInFO%20Systems%3C%2Fp%3E", "dump.txt": "%3Cp%3EDear%20%EInFO%20Systems%3C%2Fp%3E" } }

Functional Description for Input Data: a) api_key [Required]

API credentials provided by Falconide to be used while sending an email.

b) email_details [Required]

Basic details of the email to be used while sending an email. Following are included:  _{fromname [Optional]}

From name to be used for sending an email. From name need to be raw URL encoded.  from [Required]

From email address to be used while sending an email. From Domain need to authenticated first.

 replytoid [Optional]

Reply to email address to be used while sending an email. This is required in case you are expecting replies or responses on an email id which is different from the “From Email Address”.  subject [Required]

Subject to be used while sending an email. Subject need to be raw URL encoded.  content [Required]

Content to be used while sending an email. Content need to be raw URL encoded.

c) files [Optional]

(9)

API Guide v 1.6| 14/11/2013

9

 File name and file content need to be provided.

 File Content need to be raw URL encoded.

 Files is an optional part.

 Multiple file attachments are allowed.

d) settings [Optional]

Email settings to be used while sending an email. If no settings are specified, then default setting (already configured in FALCONIDE GUI) will be used. User can overwrite default settings for an API call. Following settings can be specified in an API call:

 footer

User can set footer value to zero or one in-order to disable or enable the footer respectively

 template

User can specify template Id to be used while sending an email. Only one template id can be specified.

 attachmentid

User can specify already uploaded attachments id Multiples allowed.

 clicktrack

User can set click-track value to zero or one in-order to disable or enable the click-track respectively

 opentrack

User can set track value to zero or one in-order to disable or enable the open-track respectively

 _bcc

User can specify BCC email address to be used while sending an email.

 unsubscribe

User can set unsubscribe value to zero or one in-order to disable or enable the unsubscribe respectively.

e) recipients [Required]

User can specify list of targeted user to be used while sending an email. Multiple allowed and is required.

(10)

API Guide v 1.6| 14/11/2013

10 f) attributes [Optional]

User can specify attributes for recipients to send personalized email. Attributes are optional. Multiple attributes are allowed.

g) X-APIHEADER [Optional]

User defined unique identifier for each email Length cannot be greater than 255 character

2.1.2 SMTP Based API call:

The SMTP API allows you to deliver custom handling instructions for email. You can tag your emails so that you can get detailed statistics on each tag. This is accomplished through an X-Mh-Cm-Id header that is inserted into the message. The header is a JSON encoded list of instructions and options for that email.

e.g. X-Mh-Cm-Id: { transid => [‘282747328’]};

SMTP is the fastest way to get started since it requires only minimal changes: Steps to be followed:

Change your SMTP user name and password as provided by FALCONIDE Set the server host name to smtp.falconide.com

(11)

API Guide v 1.6| 14/11/2013

11

2.2 Module: report

This API module provides all activities associated with reports of each email transactions happened on Falconide.

type= report

activity=DownloadLog (Download email activity logs for a given timespan)

Sample API URL:

https://app.falconide.com/ ?type=[XYZ] &activity=[ XYZ] &calltype=[xml/json] &data=[XYZ] 2.2.1 Activity: DownloadLog

Functional Description (Input):

CRITERIA:

a) StartDate [Optional]

Used for searching reports within a date range.

b) EndDate [Optional]

Used for searching reports within a date range.

Defaults to last one year data, if no date criteria is defined.

(12)

API Guide v 1.6| 14/11/2013

12 c) Processed

The number of mails in processed state. Value can be either 0 or 1

d) Sent

The number of mails in sent state. Value can be either 0 or 1

e) Open

The number of mails in opened state. Value can be either 0 or 1

f) Click

The number of mails in clicked state. Value can be either 0 or 1

g) Unsubscribe

The number of mails in unsubscribe state. Value can be either 0 or 1

h) Bounce

The number of mails in bounce state. Value can be either 0 or 1

i) SoftBounce

The number of mails in soft bounce state. Value can be either 0 or 1

j) HardBounce

The number of mails in hard bounce state. Value can be either 0 or 1

k) Spam

The number of mails in spam state. Value can be either 0 or 1

l) Invalid

The number of mails in invalid state. Value can be either 0 or 1

(13)

API Guide v 1.6| 14/11/2013

13 m) Dropped

The number of mails in dropped state. Value can be either 0 or 1

(If none of the above Input values are defined, API call will search for all the emails sent in the specified timespan)

n) NotifyEmail

The email id has to be provided in this tag.

The link for downloading the report file will be sent the provided email id.

p) CallbackUrl

The call back URL has to be provided in this tag. The file after downloading will be posted to this URL. Callback URL can be either http(s) or ftp.

Sample Input XML <DATASET> <CONSTANT> <ApiKey>Value</ApiKey> </CONSTANT> <CRITERIA> <StartDate>Value</StartDate> <EndDate>Value</EndDate> </CRITERIA> <INPUT> <Processed>1/0</Processed> <Sent>1/0</Sent> <Open>1/0</Open> <Click>1/0</Click> <Unsubscribe>1/0</Unsubscribe> <Bounce>1/0</Bounce> <SoftBounce>1/0</SoftBounce> <HardBounce>1/0</HardBounce> <Spam>1/0</Spam> <Invalid>1/0</Invalid> <Dropped>1/0</Dropped> <NotifyEmail>Value</NotifyEmail> <CallbackUrl>Value</CallbackUrl> </INPUT>

(14)

API Guide v 1.6| 14/11/2013

(15)

API Guide v 1.6| 14/11/2013

15

Response Description (Output):

Jobid: This tag provides the job id using which the status and other information on the job can be fetched. Output XML <DATASET> <TYPE>success</TYPE> <RECORD> <Jobid>Value</Jobid> </RECORD> < /DATASET> Input JSON "CRITERIA": { "StartDate":Value, "EndDate": Value }, "INPUT": { "Processed":"1/0", "Sent":"1/0", "Open":"1/0", "Click":"1/0", "Unsubscribe":"1/0", "Bounce":"1/0", "SoftBounce":"1/0", "HardBounce":"1/0", "Spam":"1/0", "Invalid":"1/0", "Dropped":"1/0", "NotifyEmail":Value, "CallbackUrl":Value }

(16)

API Guide v 1.6| 14/11/2013 16 Output JSON {"DATASET": { "TYPE":"success", "RECORD": { "Jobid":Value } } }

Report Download Format

Report download will be available in zip format. File name will be same as job id

eg: 4109.zip

Zip file will contain a CSV file with the requested data Below is the sample report format:

Tr-ID

X-APIHEADER To Email Address From Email Address Requested On Modified Date Mail

Size (KB) Status Remarks 7 {“3001”} [email protected] [email protected] 2013-12-01 11:11:21 2013-12-01 11:11:22 4Kb Sent 202.162.2 42.176-> 250 2.0.0 OK 4 {"2001”} [email protected] [email protected] 2013-12-01 11:01:10 2013-12-02 11:11:21 2Kb Click 202.162.2 42.176-> 250 2.0.0 OK 2 {“5001”} [email protected] [email protected] 2013-12-01 11:00:11 2013-12-01 11:00:11 8Kb Sent 202.162.2 42.176-> 250 2.0.0 OK

(17)

API Guide v 1.6| 14/11/2013

17

2.3. Module: Job

Provides all activities associated with a job. API Type value: job

Valid Activities

a) Status: view status of particular job id b) Update: update details of particular job id c) Delete: remove particular job from queue.

2.3.1 Action: Status

# JOBID [Required]

Job Id for which status is to be checked.

Input XML <DATASET> <CONSTANT> <ApiKey>Value</ApiKey> </CONSTANT> <INPUT> <JOBID>Value</JOBID> </INPUT> </DATASET>

(18)

API Guide v 1.6| 14/11/2013 18 Input JSON { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037" }, "INPUT": { "JOBID":"1" } }

JOBID: Job id requested.

Status:Status of the job.

Entered:Date when the job was added.

Output XML <DATASET> <TYPE>success</TYPE> <OUTPUT> <JOBID>Value</JOBID> <Status>Value</Status> <Entered>Value</Entered> </OUTPUT> </DATASET>

(19)

API Guide v 1.6| 14/11/2013

19

2.3.2 Action: Update

a) JOBID [Required]

Job Id for which details need to be updated

b) NotifyEmail

Email address specified to notify when job is completed or if any error occurred. Multiple allowed (comma separated)

c) CallbackUrl

URL specified to which output is to be posted.

Input XML <DATASET> <CONSTANT> <ApiKey>Value</ApiKey> </CONSTANT> <INPUT> <JOBID>Value</JOBID> <NotifyEmail>Value</NotifyEmail> <CallbackUrl>Value</CallbackUrl> </INPUT> </DATASET> Input JSON { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037" }, "INPUT": { "JOBID":"1", "NotifyEmail":"[email protected]", "CallbackUrl":"http://xyz.com/test.php" } }

(20)

API Guide v 1.6| 14/11/2013

20 Response Description (Output):

JOBID: Job ID to be updated.

Output XML <DATASET> <TYPE>success</TYPE> <OUTPUT> <JOBID>Value updated.</JOBID> </OUTPUT> </DATASET>

2.3.3 Action: Delete

# JOBID [Required]

Job Id(s) which are to be removed / deleted. Multiple allowed, comma separated

Input XML <DATASET> <CONSTANT> <ApiKey>Value</ApiKey> </CONSTANT> <INPUT> <JOBID>Value</JOBID> </INPUT> </DATASET>

(21)

API Guide v 1.6| 14/11/2013 21 Input JSON { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037" }, "INPUT": { "JOBID":"8" } }

JOBID:Job ID(s) to be removed.

Output XML <DATASET> <TYPE>success</TYPE> <OUTPUT> <RECORD><JOBID>48</JOBID><Status>Deleted</Status></RECORD> </OUTPUT> </DATASET>

(22)

API Guide v 1.6| 14/11/2013

(23)

API Guide v 1.6| 14/11/2013

23

Chapter III

Error Codes:

Error_Code Description Event

101 IP address marked as blacklisted If IP address is marked as blacklisted by FALCONIDE Team

104 API key not passed API Key not available 105 Invalid API Key

106 API call limit exceeded Number of API calls exceeds allowed limit 107 Your IP address is not allowed

1102 Invalid API call Generic error

1103 Invalid call Type specified (JSON/XML).

If call type is not defined as xml or json

1104 Invalid date format specified. Required format is "Y-m-d"

If start date and end date specified is not in required format

1105 Invalid date range specified If start date is less than end date

1106 Response parameters not specified If neither call back URL nor email-address is specified

1107 Invalid email address specified for handling response

If email address specified for response handling is invalid

1109 Error creating job. Please try again again some time

Generic error

1111 Call back URL specified is not reachable

If call back URL is not reachable

1112 Invalid Job ID passed If job ID to be queried is invalid 1113 Cannot delete job since not in

queued state

If job id to be deleted is not in queued state

(24)

API Guide v 1.6| 14/11/2013

24

(25)

API Guide v 1.6| 14/11/2013

25

Our Support Team

The Falconide support team is available to answer your questions or handle critical incidents. As delivery specialists, we can solve issues quickly – oftentimes before you even tell us. We

provide support via phone or live chat during weekdays from 9am to 7pm (IST). If you have a question, call +91-(22)-66628081

You may also submit a request online using your Falconide Account or else drop a mail to

API Guide v /11/2013

About netCORE

Table of Contents

Chapter I

Introduction

CHAPTER II:

Falconide Email API

2.1 Module: sending

2.1.1 HTTP Based API Call:

2.1.2 SMTP Based API call:

2.2 Module: report

2.3. Module: Job

2.3.2 Action: Update

2.3.3 Action: Delete

Chapter III

Error Codes:

Our Support Team