API Guide v /11/2013

Transcription

1 1

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 marketing and ranks in the top 3 in SMS services in India. Its 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 backend 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 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. 2

3 Table of Contents CHAPTER 1: Introduction...4 CHAPTER 2: Falconide API..5 REST Call..6 JSON Call.7 Functional Description for Input Data 8 SMTP Call..10 Module: Report.11 Module: Jobs 16 CHAPTER 3: Error Code.21 3

4 Chapter I Introduction 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 s. Falconide helps you focus on your business without the cost and complexity of owning and maintaining an 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 s get delivered, and handle ISP monitoring, DKIM, domain keys, SPF, feedback loops, whitelabeling, link customization and more. 4

5 CHAPTER II: Falconide 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 2. REST 5

6 2.1 Module: sending SMTP and HTTP are two methods by which can be sent to Falconide. After processing, Falconide sends the 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 per API call. The HTTP API is custom developed by Falconide, is more sophisticated and can send up to s per API call. You can use the HTTP API in cases where the same needs to be sent to multiple recipients. Since a single API call can suffice for multiple addresses, it means a significant saving in bandwidth costs HTTP Based API Call: Sample REST Call: 5 &subject=rawurlencode("weekly statement dated 1st Jan 2013") &fromname=rawurlencode("info Stats") &from=weeklystats@nsfleximail.com &replytoid=customer@nsfleximail.com &content=rawurlencode(" content here") &recipients=sach2@gmail.com,sach3@gmail.com Optional 6

7 &footer=1&template=109 (Optional if content provided) &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: { "api_key":" ", " _details":{ "fromname":"testing%20falconide", "subject":"welcome%20to%20our%20falconide%20product", "from":"weeklystats@nstest.com", "replytoid": "customer@nstest.com", "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":"sac@test.com", "attachmentid":"1,3,4", "template":"101",, "recipients":["xyz@gmail.com","abc@hotmail.com"], 7

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 . b) _details [Required] Basic details of the to be used while sending an . Following are included: fromname [Optional] From name to be used for sending an . From name need to be raw URL encoded. from [Required] From address to be used while sending an . From Domain need to authenticated first. replytoid [Optional] Reply to address to be used while sending an . This is required in case you are expecting replies or responses on an id which is different from the From Address. subject [Required] Subject to be used while sending an . Subject need to be raw URL encoded. content [Required] Content to be used while sending an . Content need to be raw URL encoded. c) files [Optional] Attachments to be used while sending an . User can send raw files as an attachment. 8

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] settings to be used while sending an . 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 . 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 open-track value to zero or one in-order to disable or enable the opentrack respectively bcc User can specify BCC address to be used while sending an . 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 . Multiple allowed and is required. 9

10 f) attributes [Optional] User can specify attributes for recipients to send personalized . Attributes are optional. Multiple attributes are allowed. g) X-APIHEADER [Optional] User defined unique identifier for each Length cannot be greater than 255 character SMTP Based API call: The SMTP API allows you to deliver custom handling instructions for . You can tag your s 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 . e.g. X-Mh-Cm-Id: { transid => [ ]; 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 Use port number 25 or 587 for sending s over SSL connections. 10

11 2.2 Module: report This API module provides all activities associated with reports of each transactions happened on Falconide. type= report activity=downloadlog (Download activity logs for a given timespan) Sample API URL: &activity=[ XYZ] &calltype=[xml/json] &data=[xyz] 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. INPUT: 11

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 12

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 s sent in the specified timespan) n) Notify The id has to be provided in this tag. The link for downloading the report file will be sent the provided 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> <Notify >Value</Notify > <CallbackUrl>Value</CallbackUrl> </INPUT> 13

14 14

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", "Notify ":Value, "CallbackUrl":Value 15

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 Address From Address Requested On Modified Date Mail Size (KB) Status Remarks 7 { 3001 sa1@gmail.com info@ymail.com :11: :11:22 4Kb Sent > OK 4 {"2001 sa2@gmail.com info@ymail.com :01: :11:21 2Kb Click > OK 2 { 5001 sa3@gmail.com info@ymail.com :00: :00:11 8Kb Sent > OK 16

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 Action: Status Functional Description (Input): # 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> 17

18 Input JSON { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037", "INPUT": { "JOBID":"1" Response Description (Output): 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> 18

19 2.3.2 Action: Update Functional Description (Input): a) JOBID [Required] Job Id for which details need to be updated b) Notify 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 Input JSON <DATASET> <CONSTANT> <ApiKey>Value</ApiKey> </CONSTANT> <INPUT> <JOBID>Value</JOBID> <Notify >Value</Notify > <CallbackUrl>Value</CallbackUrl> </INPUT> </DATASET> { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037", "INPUT": { "JOBID":"1", "Notify ":"lubanasachin@gmail.com", "CallbackUrl":" 19

20 Response Description (Output): JOBID: Job ID to be updated. Output XML <DATASET> <TYPE>success</TYPE> <OUTPUT> <JOBID>Value updated.</jobid> </OUTPUT> </DATASET> Action: Delete Functional Description (Input): # 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> 20

21 Input JSON { "CONSTANT": { "ApiKey":"a69f7b0524e9fd527c90928b6ba63037", "INPUT": { "JOBID":"8" Response Description (Output): JOBID: Job ID(s) to be removed. Output XML <DATASET> <TYPE>success</TYPE> <OUTPUT> <RECORD><JOBID>48</JOBID><Status>Deleted</Status></RECORD> </OUTPUT> </DATASET> 21

22 22

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) Invalid date format specified. Required format is "Y-m-d" If call type is not defined as xml or json 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 -address is specified 1107 Invalid address specified for handling response 1109 Error creating job. Please try again again some time 1111 Call back URL specified is not reachable If address specified for response handling is invalid Generic error 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 23

24 netcore Key Clients: 24

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) You may also submit a request online using your Falconide Account or else drop a mail to support@falconide.com 25