API Guide

Version 2.0
Confidential Falconide API Guide Version 1.9

Contents
1. Overview ................................................................................................................................................................... 3
1.1 Falconide API ....................................................................................................................................................... 3
2. Get started with Falconide API ................................................................................................................................. 3
2. 1. API Structure ..................................................................................................................................................... 3
2.2 Syntax for an API call ........................................................................................................................................... 3
3. Falconide API Library ................................................................................................................................................. 4
3.1 Module: Sending ................................................................................................................................................. 4
3.2 Module Template ................................................................................................................................................ 8
3.3 Module Domain ................................................................................................................................................ 11
3.4 Module Job........................................................................................................................................................ 12
3.5 Module Report .................................................................................................................................................. 16
4. Error Codes.............................................................................................................................................................. 19
5. Support.................................................................................................................................................................... 20

2
Confidential Falconide API Guide Version 1.9

1. Overview
Falconide is an SMTP relay service that delivers highly personalized transactional emails to the inbox within seconds
of your customer’s transaction. Falconide helps you focus on your business without the cost and complexity of
owning and maintaining an email infrastructure. It manages all the technicalities like scaling the infrastructure, ISP
outreach, reputation monitoring, whitelist services and real-time analytics. Falconide offers world class deliverability
expertise to ensure that your emails get delivered on time and into the inbox.

1.1 Falconide API

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

2. Get started with Falconide API

Falconide APIs use REST architecture in which you initiate Key authenticated JSON calls over HTTPS.

The procedure to use an API is:

1. Enable API access in Falconide’s panel.

2. Submit a request via HTTPS POST to Falconide. For best results, use HTTPS POST.
3. Submit a call for each function. You can combine multiple calls in one HTTP request. (The maximum number of
requests depends on the HTTP payload, the limit being 5 MB).

Falconide APIs support JSON as well as REST formats. In this document, JSON samples are given for your
understanding.

2. 1. API Structure
Each API Call consist of three parts:

1. API URL
2. API Key : You can obtain the unique API API key from your Falconide panel, at Settings -> API.
3. Input Data: comprise raw parameters like email, templateid, fromname, subject, etc.

2.2 Syntax for an API call

The general syntax of an API call is shown here:

<API URL> [value] </API URL>

<API key> [value] <API key/>
<INPUT>
<Parameter 1> [value] </parameter1>
<Parameter 2> [value] </parameter2>
</INPUT>

3
Confidential Falconide API Guide Version 1.9

3. Falconide API Library

Here is the list of APIs offered by Falconide. These are explained in detail later in the document.

1. Sending (email)
2. Templates: Add, Edit, Preview
3. Domain
4. Jobs: View (status), Update, Delete
5. Reports

3.1 Module: Sending

Falconide can receive emails through SMTP and HTTP as well. After processing the email, it sends the email to the
target server via Internet through SMTP only.

SMTP is a standard protocol, relatively simpler to implement, and it sends one email per API call.

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.

If you wish to send the same content to multiple recipients, you can use a single API. One API call can suffice for
multiple email addresses, helping in significant saving of bandwidth costs.

SMTP based API Call for email Sending:

SMTP API allows you to deliver custom handling instructions for email. You can categorize your emails with
tags like Sign up, Confirmation emails, etc. to get detailed statistics on each tag. You can tag the emails by
inserting X-TAGS in the header of the message.

You can also track each message with an identifier. Pass the required tracking data under the X-
APIHEADER. The X-APIHEADER header is a JSON-encoded associative array.

Here is a sample:

X-APIHEADER: { transid => [‘282747328’],};

X-TAGS: Account Deactivation, Verification;

SMTP is a fast way to get started since it requires very few changes.

4
Confidential Falconide API Guide Version 1.9

To set up SMTP API call:

a. Change your SMTP user name and password as per the credentials provided to you.
b. Set the server host name to smtp.falconide.com.
c. Use port number 25 or 587 for sending emails over SSL connections.

HTTP based API Call for Email Sending:

Input Parameters for email Sending API:

a. API key [Required]: API credentials provided by Falconide to be used while sending an email.
b. Email details [Required]: are the basic details of the email to be used while sending an email. The details
comprise the following fields:
i. Fromname [Optional]: From name to be used in the email. It needs to be raw URL encoded.
ii. from [Required] : The From email address to be used in sending an email. The From Domain must be
authenticated first.
iii. replytoid [Optional] : Reply to email address to be used in the email. You need to provide a value to
this field in cases when you are expect recipient’s responses on an email id which is different from the
From Email Address.
iv. subject [Required] :Subject to be used in the email.
v. content [Required] : Content to be used in the email.

Note: Fromname, subject, and content need to be raw URL encoded.

c. Files [Optional]: are the attachments to be used in sending an email. You can send raw files as an
attachment. Name and content of the files must be provided. The file content needs to be base64
encoded or raw URL encoded,preferably, base64 encoded to avoid performance issues. 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 configured in your Falconide panel is used. You can overwrite default settings for
an API call. Following settings can be specified in an API call:
i. Footer: Set the value to zero or one to disable or enable the footer respectively.
i. Template: Specify template Id to be used while sending an email. Only one template id can be
specified.
ii. Attachmentid: Specify already uploaded attachments id. Multiples allowed.
iii. Clicktrack: Set click-track value to zero or one to disable or enable the click-track
respectively.

5
Confidential Falconide API Guide Version 1.9

iv. Opentrack: Set the open-track value to zero or one to disable or enable the open-track
respectively.
v. Bcc: Specify BCC email address to be used while sending an email.
i. Unsubscribe: Set unsubscribe value to zero or one to disable or enable unsubscribe
respectively.
e. Recipients [Required]: Specify list of targeted users to be used while sending an email. Multiple
recipients are allowed.
f. cc feature [Optional]: Specify one or more CC Id per recipient while sending an email.
g. Attributes [Optional]: Specify attributes for recipients to send personalized email. Multiple
attributes are allowed.
h. X-APIHEADER [Optional]: User-defined unique identifier for each email. The length of X-APIHEADER
cannot be more than 255 characters.
i. Tags: Mark the emails send through Falconide with these unique identifiers. You can search specific
emails from email logs like Sign up, Confirmation, Thank You mailers, etc based on these tags.
Length of tags cannot be greater than 255 characters.

Samples are provided here for JSON as well as REST API call.

6
Confidential Falconide API Guide Version 1.9

HTTP based API Call for email Sending:

 JSON

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]",

"tags": "Account Deactivation, Verification",

"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]"],
"X-APIHEADER": ["ACC123",”SE2532”],
“recipients_cc”: [
“[email protected],[email protected]”,”[email protected],sample
6email@ xyz.com” ],
"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"
}
}
7
Confidential Falconide API Guide Version 1.9

 REST

https://api.falconide.com/falconapi/web.send.rest?api_key=554dgdfgfg5r45
4345345retet52355 &subject=rawurlencode("Weekly statement dated 1st Jan
2013")
&fromname=rawurlencode("Info Stats")
&[email protected]
&[email protected]
&tags="Account Deactivation, Verification"
&content=rawurlencode(" Email content here")
&[email protected],[email protected]
&X-APIHEADER=”ACC123,SE2532”
&[email protected]|[email protected],[email protected]|[email protected]
Optional
&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)

3.2 Module Template

This module enables you to create and manage your email templates. The activities associated with this
module are: Add, Edit, and Preview templates.

3.2.1 Add Template

This API enables you to add email templates.

a. API key [Required]: API credentials provided by Falconide to be used while sending an email.
j. Template name[Required] :Template name required while creating a template.
b. Content [Required] : Content to be used while sending an email. Content needs to be raw URL encoded.

8
Confidential Falconide API Guide Version 1.9

Sample JSON Input:

https://api.falconide.com/api/falcon.domains?data=
{
"apikey":"<api_key>",
"type" : "templateadd",
"templatename" : "<sample_template_name>",
"content" : "<template_content>"
}

Output:

Success

{
"status": "success",
"templateid": "1922",
"message": "Data added successfully in Falconide."
}

Failure

{
"status": "error",
"message": "error adding template" // If
Template name already exists
}

3.2.2 Edit Template

This API enables you to edit the templates. The input parameters are:

a. API key [Required] : API credentials provided by Falconide to be used while sending an email.
b. template name[Required]: Template name required while creating a template.
c. content [Required] : Content to be used while sending an email. Content needs to be raw URL encoded.
d. template id[Required]: Specify the template ID to be used while editing the template content. Only
one template id can be specified.

9
Confidential Falconide API Guide Version 1.9

Sample JSON Input:

https://api.falconide.com/api/falcon.domains?data=
{
"apikey":"<api_key>",
"type" : "templateadd",
"templatename" : "<sample_template_name>",
"content" : "<template_content>",
"templateid" : "<template_id>"

Output:

Success

{
"status": "success",
"message": "Data updated successfully in Falconide."
}

Failure:

{
“status": "error",
"message": "error adding template //If Template id or Template name is
missing
}

3.2.3 Preview Template

This API enables you to preview the templates. The input parameters are:

a. API key [Required]: API credentials provided by Falconide to be used while sending an email.
b. Template id [Required]: ID of the template which needs to be previewed/downloaded.

10
Confidential Falconide API Guide Version 1.9

Sample JSON Input:

https://api.falconide.com/api/falcon.domains?data=
{
apikey:<api_key>,
type:<templatedownload>,
templateid:<template_id>
}

Output:

Success:

{
“status": "error",
"message": "No template found for you" //Invalid
Template id
}

Failure:

{
“status": "error",
"message": "Missing template id" // Missing
Template id}

3.3 Module Domain

This API module enables you to add domains which can be used for sending emails. The input parameters are:

a. api_key [Required]: API credentials provided by Falconide to be used while sending an email.
b. domain name[Required]: Domain name to be mentioned which needs to be created.

11
Confidential Falconide API Guide Version 1.9

Sample JSON Input:

https://api.falconide.com/api/falcon.domains?data=
{
"apikey":"<api_key>",
"type" : "domadd",
"domainname" : "<sample_domain>"
}

Output:

Success

{
"status": "success",
"message": "Data updated successfully in Falconide."
}

Failure

{
"status": "error",
// domain already exists
"message": "Domain is already in use"
}

3.4 Module Job

These APIs enable you to perform activities associated with Jobs.

3.4.1 View Status

You can view the status of a particular job ID. The input parameter is:

JobID [Required]: Job Id for which status is to be checked.

12
Confidential Falconide API Guide Version 1.9

Sample Input XML

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

Output XML

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

Sample Input JSON

{
"CONSTANT": {
"ApiKey":"a69f7b0524e9fd527c90928b6ba63037"
},
"INPUT": {
"JOBID":"1"
}
}

13
Confidential Falconide API Guide Version 1.9

Output:

JOBID: Job id requested.

Status: Status of the job.
Entered: Date when the job was added.

3.4.2 Update
This API enables you to update an existing job. The input parameters are:

JOBID [Required]: ID of the job whose details need to be updated.

NotifyEmail: Specify the email address to which you want to receive the notification of the job status.
You can provide multiple email addresses, separated by commas.

CallbackUrl: Specify the URL to which output is to be posted.

Sample Input XML

<DATASET>
<CONSTANT>
<ApiKey>Value</ApiKey>
</CONSTANT>
<INPUT>
<JOBID>Value</JOBID>
<NotifyEmail>Value</NotifyEmail>
<CallbackUrl>Value</CallbackUrl>
</INPUT>
</DATASET>

Output XML

{
"CONSTANT": {
"ApiKey":"a69f7b0524e9fd527c90928b6ba63037"
},
"INPUT": {
"JOBID":"1",
"NotifyEmail":"[email protected]",
"CallbackUrl":"http://xyz.com/test.php"
}
}

Response Description (Output):

JOBID: Job ID to be updated.

14
Confidential Falconide API Guide Version 1.9

Output XML

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

4.3 Delete
This API enables you to delete the jobs. The input parameter is:
JOBID [Required]: Job Id(s) which are to be removed / deleted. You can provide multiple job ids, separated
by commas.

Input XML

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

Output XML

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

15
Confidential Falconide API Guide Version 1.9
Input JSON

{
"CONSTANT": {
"ApiKey":"a69f7b0524e9fd527c90928b6ba63037"
},

"INPUT": {
"JOBID":"8"
}
}

Response Description (Output):

JOBID: Job ID(s) to be removed.

3.5 Module Report

This API enables you to download the report of each email transaction happening through Falconide. The
input parameters are:

a. StartDate [Optional]: Used for searching reports within a date range.

b. EndDate [Optional]: Used for searching reports within a date range. If no date criteria is defined
last one year data is retreived.
c. Processed: Number of mails in processed state. The value of this parameter can be 0 or 1.
d. Sent: Number of mails in sent state. The value of this parameter can be 0 or 1.
e. Open: Number of mails in opened state. The value of this parameter can be 0 or 1.
f. Click: Number of mails in clicked state. The value of this parameter can be 0 or 1.
g. Unsubscribe: Number of mails in unsubscribe state. The value of this parameter can be 0 or 1.
h. Bounce: Number of mails in bounce state. The value of this parameter can be 0 or 1.
i. SoftBounce: Number of mails in soft bounce state. The value of this parameter can be 0 or 1.
j. HardBounce: Number of mails in hard bounce state. The value of this parameter can be 0 or 1.
k. Spam: Number of mails in spam state. The value of this parameter can be 0 or 1.
l. Invalid: Number of mails in invalid state. The value of this parameter can be 0 or 1.
m. Dropped: Number of mails in dropped state. The value of this parameter can be 0 or 1.

16
Confidential Falconide API Guide Version 1.9
Note: If the parameters from (c) to (m) are optional. If not defined, then the API call searches for all
the emails sent in the specified timespan.
n. NotifyEmail: Specify the email address to which the report download link has to be sent.
o. CallbackUrl: Specify the call back URL to which the downloaded report file is to be posted. The
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>

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>

17
Confidential Falconide API Guide Version 1.9
Sample 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
}

Output JSON

{"DATASET":
{
"TYPE":"success",
"RECORD":
{
"Jobid":Value
}
}
}

Format of the downloaded Report

Report download is available in zip format and the job id for the report request is the report file name. The zip file
comprises a CSV file with the requested data.

For example, if the job id for the report request is 4109, the zip file of the report is named as 4109.zip.

18
Confidential Falconide API Guide Version 1.9

Below is the sample report format:

Tr- X- To Email From Email Requested Modified Date Mail Status Remarks
ID APIHEADER Address Address On Size
(KB)

7 {“3001”} sa1@gmail info@ymail. 2013-12- 2013-12-01 4Kb Sent 202.162.242

.com com 01 11:11:22 .176-> 250
11:11:21 2.0.0 OK

4 {"2001”} sa2@gmail info@ymail. 2013-12- 2013-12-02 2Kb Click 202.162.242

.com com 01 11:11:21 .176-> 250
11:01:10 2.0.0 OK

2 {“5001”} sa3@gmail info@ymail. 2013-12- 2013-12-01 8Kb Sent 202.162.242

.com com 01 11:00:11 .176-> 250
11:00:11 2.0.0 OK

4. Error Codes
Here is the error code list:

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 If call type is not defined as xml or json
(JSON/XML).
1104 Invalid date format specified. If start date and end date specified is not
Required format is "Y-m-d" 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 If email address specified for response
handling response handling is invalid
1109 Error creating job. Please try again Generic error
after some time

19
Confidential Falconide API Guide Version 1.9
1111 Call back URL specified is not If call back URL is not reachable
reachable
1112 Invalid Job ID passed If job ID to be queried is invalid
1113 Cannot delete job since not in If job id to be deleted is not in queued
queued state state

5. Support
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
[email protected].

20