Manage And Connect Using APIs

APIs

Zoho Campaigns allows you to perform campaign operations without having the need to log in. And, that's why we offer API keys. It's pretty easy and neat. You can view data relating to two operations, namely:

  • List Management
  • Campaign Management

There is a set of must-use parameter types to be entered while you invoke your request. These types will differ from case-to-case. Use our API keys to keep track of what's happening with a campaign or a list.

However, there are certain formats followed for the response which, the user can define during the time of request. The two types used are XML being our default response type (or) JSON if declared during request.

Having said that, to start with:

1. List Management Using APIs

1.1 Contact Subscribe

Users can subscribe to a list without using the signup form nor by getting added by a contact. They can subscribe using our API key and the user added will be notified.

Request URL:

Unlike the request URL formats in the above operations, you've an option of XML (or) JSON here at the time of request.

XML: https://campaigns.zoho.com/api/xml/listsubscribe.do

JSON: https://campaigns.zoho.com/api/json/listsubscribe.do

Request Type: Post

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
listkey* String List Api Key to send a subscription mail to Contacts
version String This will fetch responses based on the current API version
resfmt String XML (or) JSON
contactInfo XML (or) JSON Contact email with other fields. Format of this value depends on the request URL.

* - Mandatory Parameters

Sample Request:

XML:

https://campaigns.zoho.com/api/xml/listsubscribe?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&listkey=[ListApiKey]&contactinfo=macjay@testcmp.zoho.com

JSON:

https://campaigns.zoho.com/api/json/listsubscribe?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&listkey=[ListApiKey]&contactinfo={First Name:mac,Last Name:Last Name,Contact Email:jai@zoho.com}

Response:

Our API response will let you know of the following be it in the XML or JSON format:

Status - Request status, which is either Success or Error.
Code - Your error code in the response.

We’ve a set of codes that has certain values which are:

Code Values
0 success
1001 Pattern doesn’t match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized key
2001 Error in subscription. Please retry after sometime
2002 Iist key is empty or Invalid List key
2003 Contact exists in this list

XML Format:

<response uri="/api/xml/listsubscribe" version="1">
<code>0</code>
<status>success</status>
<message>A confirmation email is sent to the user. User needs to confirm to successfully subscribe.</message>
</response>

JSON format

{"message":"A confirmation email is sent to the user. User needs to confirm to successfully subscribe.","status":"success","code":"0","uri":"/api/json/listsubscribe","version":"1"}

1.2 Contact Unsubscribe

Not interested in being part of the email subscription? Never mind, all you need to do is enter the API key to unsubscribe and the user will be notified.

Request URL:

XML: https://campaigns.zoho.com/api/xml/listunsubscribe

JSON: https://campaigns.zoho.com/api/json/listunsubscribe

Request Type: Post

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API key to access your account
API key to access your account (Campaigns API)
listkey* String List Api Key use to Unsubscribe Contacts
version String This will fetch responses based on the current API version
resfmt String XML (or) JSON
contactInfo XML (or) JSON Contact email with other fields. Format of this value depends on the request URL.

* - Mandatory Parameters

Sample Request:

XML:

https://campaigns.zoho.com/api/xml/listunsubscribe?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&listkey=[ListApiKey]&contactinfo=<xml><fl val="First Name">mac</fl><fl val="Contact Email">jai@zoho.com</fl></xml>

JSON:

https://campaigns.zoho.com/api/json/listunsubscribe?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&listkey=[ListApiKey]&contactinfo={First name:mac,Last Name:Last Name,Contact Email:jai@zoho.com}

Response:

Our API response will let you know of the following be it in the XML or JSON format:

Status - Request status, which is either Success or Error.
Code - Your error code in the response.

We’ve a set of codes that has certain values which are:

Code Values
0 Success
1001 Pattern doesn’t match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized key
2101 Error in unsubscription. Please retry after sometime
2102 Listkey is empty or Invalid Listkey
2103 Subscriber does not exist

XML Format

<response uri="/api/xml/listunsubscribe" version="1">
<code>0</code>
<status>success</status>
<message>User successfully unsubscribed.</message>
</response>

JSON format

{"message":"User successfully unsubscribed.","status":"success","code":"0","uri":"/api/json/listunsubscribe","version":"1"}

1.3 Total Contacts

You don’t have to do a research on how effective a list has been or how much reach does a particular list measure. Find out using our API key to find out the number of subscribers in a list.

Request URL:

https://campaigns.zoho.com/api/listsubscriberscount

Request Type: Get

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
listkey* String List API Key to send a subscription mail to contacts
version String This will fetch responses based on the current API version
resfmt String XML (or) JSON

* - Mandatory Parameter

Sample Request:

https://campaigns.zoho.com/api/listsubscriberscount?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&listkey=[ListApiKey]

Response:

Our API response will let you know of the following be it in the XML or JSON format:

Status - Request status, which is either Success or Error.
Code - Your error code in the response.
Total List Count - Gives you the count of all the contacts in the list.

We’ve a set of codes that has certain values which are:

Code Values
0 Success
1001 Pattern doesn’t match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized key
2201 Error in displaying count. Please retry after sometime
2202 List key is empty or Invalid

XML format

<response uri="/api/listsubscriberscount" version="1"><code>0</code><status>success</status><no_of_contacts>2</no_of_contacts></response>

JSON format

{"status":"success","code":"0","uri":"/api/listsubscriberscount","no_of_contacts":2,"version":"1"}

2. Campaign Management Using APIs

2.1 Recent Campaign

Use our API key to view recent campaigns in this account. Irrespective of what status campaigns are in - be it draft, sent, stopped, canceled or more, we would let you know the status of all the campaigns.

Request URL:
https://campaigns.zoho.com/api/recentcampaigns

Request Type: Get

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API Key to access account
API key to access account (Campaigns API)
limit* Integer Limit to fetch recent campaigns from campaigns list
version String This will fetch responses based on the current API version

* - Mandatory Parameter

Sample Request:

https://campaigns.zoho.com/api/recentcampaigns?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]

Response:

Our API response will let you know of the following, be it in the XML or JSON format:

Status - Request status, which is either Success or Error.
campaign_status - Lets you know the current status of the campaign.
sent_time - Gives you data of when this campaign was last sent.
created_time - Gives you data of when this campaign was created.
campaign_api_key - The API key used to fetch recent campaign details.
campaign_name - The name of the campaign.
Code - Your error code in the response.

We’ve a set of codes that has certain values which are:

Code values
0 SUCCESS
1001 Pattern doesn't match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized request
6101 No campaigns are available in this view

XML Format:

<response uri="/api/recentcampaigns" version="1"><br/>
<status>success</status><br/>
<code>0</code><br/>
<recent-campaigns><br/>
<campaign no="1"><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b99f747d905612a4b</fl><br/>
<fl val="sent_time">1342503703000</fl><br/>
<fl val="campaign_status">Sent</fl><br/>
<fl val="created_time">1342503640000</fl><br/>
</Campaign><br/>
<campaign no="2"><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b56febfd0cb811b03</fl><br/>
<fl val="sent_time">1342503459000</fl><br/>
<fl val="campaign_status">Sent</fl><br/>
<fl val="created_time">1342503425000</fl><br/>
</campaign><br/>
<campaign no="3"><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b2bf0c3fb3e40110b</fl><br/>
<fl val="sent_time">1342502423000</fl><br/>
<fl val="campaign_status">Sent</fl><br/>
<fl val="created_time">1342502300000</fl><br/>
</campaign><br/>
<campaign no="4"><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b1f0db88921e34a27</fl><br/>
<fl val="campaign_status">Draft</fl><br/>
<fl val="created_time">1342502300000</fl><br/>
</campaign><br/>
<campaign no="5"><br/>
<fl val="campaign_name">123</fl><br/>
<fl val="campaign_api_key">34594177d382061bc947299b74895e93</fl><br/>
<fl val="campaign_status">Draft</fl><br/>
<fl val="created_time">1342501243000</fl><br/>
</campaign><br/>
</recent-campaigns><br/>
</response>

JSON format:

{"status":"success","recent_campaigns":"[{campaign_name=CAMPAIG, campaign_api_key=34594177d382061b99f747d905612a4b, sent_time=1342503703000, campaign_status=Sent, created_time=1342503640000}, {campaign_name=CAMPAIG, campaign_api_key=34594177d382061b56febfd0cb811b03, sent_time=1342503459000, campaign_status=Sent, created_time=1342503425000}, {campaign_name=CAMPAIG, campaign_api_key=34594177d382061b2bf0c3fb3e40110b, sent_time=1342502423000, campaign_status=Sent,created_time=1342502300000}, {campaign_name=CAMPAIG, campaign_api_key=34594177d382061b1f0db88921e34a27, campaign_status=Draft, created_time=1342502300000}, {campaign_name=123, campaign_api_key=34594177d382061bc947299b74895e93, campaign_status=Draft, created_time=1342501243000}]","code":"0","uri":"/api/recentcampaigns","version":"1"}

2.2 Recently Sent Campaign

You might want to reflect campaign data in your website. Use our API key to view the email campaign that was recently sent. Using this API will help you fetch details only of the recently sent campaign and not other campaign(s) in a different status.

Request URL:

https://campaigns.zoho.com/api/recentsentcampaigns

Request Type: Get

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
limit* Integer Limit to fetch Recent campaigns from campaigns list
version String This will fetch responses based on the current API version
resfmt String XML (or) JSON

* - Mandatory Parameter

Sample Request:

https://campaigns.zoho.com/api/recentsentcampaigns?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]

Response:

Our API response will let you know of the following be it in the XML or JSON format:

Status - Request status, which is either Success or Error.
email_status - Lets you know the current status of the campaign.
last_sent_time - Gives you data of when this campaign was last sent.
campaign_api_key - The API key used to fetch recent campaign details.
email_name - The name of the campaign.
Code - Your error code in the response.

We’ve a set of codes that has certain values which are:

Code values
0 SUCCESS
1001 Pattern doesn't match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized request
6201 No campaigns are available in this view

XML Format:

<response uri="/api/recentsentcampaigns" version="1"><br/>
<status>success</status><br/>
<code>0</code><br/>
<recent-sent-campaigns><br/>
<campaign no="1"><br/>
<fl val="sent_time">1342503703000</fl><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b99f747d905612a4b</fl><br/>
<fl val="created_time">1342503640000</fl><br/>
</campaign><br/>
<campaign no="2"><br/>
<fl val="sent_time">1342503459000</fl><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b56febfd0cb811b03</fl><br/>
<fl val="created_time">1342503425000</fl><br/>
</campaign><br/>
<campaign No="3"><br/>
<fl val="sent_time">1342502423000</fl><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="campaign_api_key">34594177d382061b2bf0c3fb3e40110b</fl><br/>
<fl val="created_time">1342502300000</fl><br/>
</campaign><br/>
</recent-sent-campaigns><br/>
</response>

JSON Format:

{"recent_sent_campaigns":"[{sent_time=1342503703000, campaign_name=CAMPAIG, campaign_api_key=34594177d382061b99f747d905612a4b, created_time=1342503640000}, {sent_time=1342503459000, campaign_name=CAMPAIG, campaign_api_key=34594177d382061b56febfd0cb811b03, created_time=1342503425000}, {sent_time=1342502423000, campaign_name=CAMPAIG, campaign_api_key=34594177d382061b2bf0c3fb3e40110b, created_time=1342502300000}]","status":"success","code":"0","uri":"/api/recentsentcampaigns","version":"1"}

2.3 Campaign Reports

Urged to analyze statistical reports and the effectiveness of your email campaign? It’s easy, no one has to share reports to you, nor do you have to log in, use our API key and view the campaign report of a particular email campaign.

Request URL:

https://campaigns.zoho.com/api/campaignreports

Request Type: Get

Parameters:

Parameter Data Type Description
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
campaignkey* String Fetch campaigns reports from campaign list
version String This will fetch responses based on the current API version
resfmt String XML (or) JSON

* - Mandatory Parameter

Sample Request:

https://campaigns.zoho.com/api/campaignreports?authtoken=[AUTHTOKEN]&scope=[CampaignsAPI]&version=1&resfmt=[XML/JSON]&campaignkey=[CampaignApiKey]

Response:

Our API response will let you know of the following be it in the XML or JSON format:
Status - Request status, which is either Success or Error.
Code - Your error code in the response.

We’ve a set of codes that has certain values which are:

Code values
0 SUCCESS
1001 Pattern doesn't match
1002 Extra parameter found
1003 No mandatory fields in this URL
1004 Wrong URL entered
1005 Please enter correct data type format
1006 Multiple key entries are not supported
1007 Unauthorized request
6001 Error in displaying reports. Please retry after sometime
6002 Invalid Campaign key

XML Format

<response uri="/api/campaignreports" version="1"><br/>
<status>success</status><br/>
<code>0</code><br/>
<campaign-reports><br/>
<fl val="spams_count">0</fl><br/>
<fl val="clicks_count">2</fl><br/>
<fl val="opens_count">2</fl><br/>
<fl val="forwards_count">0</fl><br/>
<fl val="campaign_name">CAMPAIG</fl><br/>
<fl val="emails_sent_count">2</fl><br/>
<fl val="optouts_count">0</fl><br/>
<fl val="bounces_count">0</fl><br/>
</campaign-reports><br/>
</response>

JSON format:

{"status":"success","clicks_count":"2","opens_count":"2","campaign_name":"CAMPAIG","code":"0","uri":"/api/campaignreports","optouts_count":"0",
"bounces_count":"0","version":"1","spams_count":"0","forwards_count":"0","emails_sent_count":"2"}

To access API keys:

Campaign Management:

Please note that for operations related to campaign management, use only the campaign API key.

  • Click Settings --> API & Call Back
  • Copy API Key

List Management:

Please note that for operations related to list management, you are adviced to use both - the campaign API and the list API

Campaign API Key:

  1. Click Settings --> API & Call Back
  2. Copy API

List API Key:

  1. Click Contacts --> Mailing lists
  2. Click open the list --> Show API List Key
  3. Copy the key

Note:

  • To access the API of a respective list, signups to the particular list should be allowed

Note:
In any given scenario, be it any kind of API, we advice you to follow what is given in this document. These API keys are sensitive and any kind of typo during request could result in an error case. However, we thought we should let you know of some points to keep in mind:

  • Default responses will always be in XML format.
  • HTTP instead of HTTPS in the request URL is not supported.
  • Custom fields in the request URL can be declared with the field itself.
  • During list subscription, If custom field value limit exceeds, the field will not be recorded even though the contact will be subscribed to the list(s).
  • To subscribe or unsubscribe to and from a list, Email is mandatory.
  • For you to access data with regards to 1.2 and 1.3 the list should consist of atleast one contact.
  • API keys are applicable for those lists that allow subscriptions.

Having said that please write to us at support@zohocampaigns.com in case you need further assistance.