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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
listkey*StringList Api Key to send a subscription mail to Contacts
versionStringThis will fetch responses based on the current API version
resfmtStringXML (or) JSON
contactInfoXML (or) JSONContact 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:

CodeValues
0success
1001Pattern doesn’t match
1002Extra parameter found
1003No mandatory fields in this URL
1004Wrong URL entered
1005Please enter correct data type format
1006Multiple key entries are not supported
1007Unauthorized key
2001Error in subscription. Please retry after sometime
2002Iist key is empty or Invalid List key
2003Contact 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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API key to access your account
API key to access your account (Campaigns API)
listkey*StringList Api Key use to Unsubscribe Contacts
versionStringThis will fetch responses based on the current API version
resfmtStringXML (or) JSON
contactInfoXML (or) JSONContact 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:

CodeValues
0Success
1001Pattern doesn’t match
1002Extra parameter found
1003No mandatory fields in this URL
1004Wrong URL entered
1005Please enter correct data type format
1006Multiple key entries are not supported
1007Unauthorized key
2101Error in unsubscription. Please retry after sometime
2102Listkey is empty or Invalid Listkey
2103Subscriber 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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
listkey*StringList API Key to send a subscription mail to contacts
versionStringThis will fetch responses based on the current API version
resfmtStringXML (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:

CodeValues
0Success
1001Pattern doesn’t match
1002Extra parameter found
1003No mandatory fields in this URL
1004Wrong URL entered
1005Please enter correct data type format
1006Multiple key entries are not supported
1007Unauthorized key
2201Error in displaying count. Please retry after sometime
2202List 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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API Key to access account
API key to access account (Campaigns API)
limit*IntegerLimit to fetch recent campaigns from campaigns list
versionStringThis 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:

Codevalues
0SUCCESS
1001Pattern doesn't match
1002Extra parameter found
1003No mandatory fields in this URL
1004Wrong URL entered
1005Please enter correct data type format
1006Multiple key entries are not supported
1007Unauthorized request
6101No 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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
limit*IntegerLimit to fetch Recent campaigns from campaigns list
versionStringThis will fetch responses based on the current API version
resfmtStringXML (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:

Codevalues
0SUCCESS
1001Pattern doesn't match
1002Extra parameter found
1003No mandatory fields in this URL
1004Wrong URL entered
1005Please enter correct data type format
1006Multiple key entries are not supported
1007Unauthorized request
6201No 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:

ParameterData TypeDescription
Authentication:
authtoken*
scope*
String
String
API key to access account
API key to access account (Campaigns API)
campaignkey*StringFetch campaigns reports from campaign list
versionStringThis will fetch responses based on the current API version
resfmtStringXML (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:

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