API

Zoho Campaigns允许您无需登录即可执行宣传推广操作。而且，这就是为什么我们会提供API密钥。这是很容易和简洁的。您可以查看数据相关的2个操作，即：

• 列表管理
• 宣传推广管理

当您调用您的请求时，要输入一组必须使用的参数类型。这些类型在不同情况下将是不同的。使用我们的API密钥来跟踪一个宣传推广或一个列表发生了什么。

然而，用户在请求期间可以定义一些特定格式的响应。所用到的2种类型是作为默认响应类型的XML（或）JSON（若在请求期间声明了的话）。

既然如此，开始：

1. 使用API列表管理

1.1 联系订阅

用户可以不通过使用注册表或添加一个联系人来订阅列表。他们可以使用我们的API密钥订阅并且添加的用户会被通知。

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:

JSON format

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:

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.
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

JSON format

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

JSON format

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:

JSON format:

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:

JSON Format:

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

JSON format:

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.