Zoho Mail REST APIs Getting Started

Prerequisites

1. You need a valid Zoho Mail account to use the API. Sign up or Login to Zoho Mail to access the services.
2. Ensure you have the necessary permissions from your system administrator to access and use the API services.
3. Generate a valid OAuth token to authenticate your API requests. Refer to Zoho's OAuth Token Guide for instructions.
4. Confirm that your user account has the appropriate role to access the required API endpoints.
5. Host your application on a custom-maintained server that can handle API requests and responses.
6. Ensure a stable internet connection to send API requests and receive responses from Zoho Mail's servers.
    

Multiple Data Centers

Zoho Mail is hosted in multiple data centers across various regions, each associated with a different domain. There are seven distinct domains for Zoho Mail APIs, and you need to use the domain that corresponds to your data center.

The APIs referenced on this page are for organizations hosted on the .com domain. If your organization uses a different domain, you must replace .com with the appropriate domain in the API endpoints before using them.

HTTP Methods

Zoho Mail is hosted in multiple data centers, making it available on different domains. There are seven different domains for Zoho Mail's APIs, and you will have to use the one that applies to you.

Common Terminologies Used

• Zoho Organization ID (zoid)

  Description: The Zoho Organization ID is a unique identifier assigned to each organization. You need this ID for making API requests related to domain and organization.
  How to Retrieve: You can fetch the zoid by using the Get Organization Details API.

• Zoho User ID (zuid)

  Description: The Zoho User ID is a unique identifier specific to each user. You need this ID when making user-specific API calls.
  How to Retrieve (User): Users can find their zuid by clicking their avatar at the top right corner of their Zoho Mail interface. The User ID displayed in the popup as Zoho User ID is the zuid.
  How to Retrieve (Admin): If you are an Admin and want to retrieve the zuid for all users in your organization, use the Fetch Organization User Details API.

• Account ID (accountId)

  Description: The Account ID is a unique identifier assigned to each account within Zoho Mail. Users may have multiple accounts, including external POP accounts, each with a distinct Account ID.
  How to Retrieve: You can retrieve a user's Account ID using the Fetch a Specific User Details API (requires zuid) or get Account IDs for all users using the Fetch all Org User Details API (requires zoid).

• Group ID (zgid)

  Description: A group is an email distribution list that allows multiple users to share a common email address for team or departmental communication. Group members receive and manage emails collectively, enhancing collaboration. The Group ID is the unique identifier assigned to each group within an organization.
  How to Retrieve: You can retrieve the Group ID of all the groups in your organization by using the Get All Groups Details API.

• Folder ID (folderId)

  Description: Each folder in your Zoho Mail account has a unique folder ID. This includes folders in any POP accounts you may have added, each of which will also have a distinct ID. 
  How to Retrieve: Use the Get All Folder Details API to fetch the Folder ID for all folders in your account.

• Label ID (labelId)

  Description: Labels in Zoho Mail allow users to categorize emails. Each label has a unique Label ID.
  How to Retrieve: You can obtain the Label ID using the Get All Label Details API.

• Message ID (messageId)

  Description: Your Zoho Mail account assigns a unique Message ID to every email. This ID is essential for message-specific API requests, such as marking an email as read or retrieving email headers.
  How to Retrieve: To fetch the Message ID of emails, use the List of Emails in a Folder API for a specific folder or the List Emails Based on Search Parameters API for emails matching specific search criteria.

• Thread ID (threadId)

  Description: A thread represents a series of related email messages grouped together based on the conversation. This includes all replies and forwards related to the original message. A Thread ID is a unique identifier assigned to each thread. The thread ID is used to reference and manage the entire conversation within the thread.
  How to Retrieve: The List of Emails in a Folder API provides messages with their Thread IDs, while the List Emails Based on Search Parameters API returns messages matching specific search criteria along with their Thread IDs.

• Task ID (taskId)

  Description: Tasks represent actionable items, such as to-do lists of the user. A Task ID is a unique identifier assigned to each task in Zoho Mail. 
  How to Retrieve: You can obtain the Task ID using the Get All Tasks in a Group/Personal Tasks API.

• Bookmark ID (bookmarkId)

  Description: Bookmarks in Zoho Mail allow users to save and organize web links. A Bookmark ID is a unique identifier for each bookmark.
  How to Retrieve: You can obtain the Bookmark ID using the Get All Bookmarks API.

• Note ID (noteId)

  Description: Notes in Zoho Mail are user-created text entries for storing information. A Note ID is a unique identifier for each note.
  How to Retrieve: You can obtain the Note ID using the Get All Notes API.

Making the First API Request : Sending an Email via Zoho Mail API

Below is a step-by-step guide to making your first API request using Zoho Mail's REST API to send an email.

Step 1: Get OAuth Token

Before making the API call, you need an OAuth token to authenticate your requests. Follow Zoho Mail's OAuth Token Guide to generate one.

Step 2: HTTP Method and API Endpoint

HTTP Method : POST
API Endpoint : https://mail.zoho.com/api/accounts/{accountId}/messages

Step 3: Sample CURL Request

Note : Make sure to replace {accountId} with your account ID and *********** with your Zoho OAuth token.

Step 5: Sample JSON Response

Successful Response: 

Unsuccessful Response:

For more details, refer Response Codes in Zoho Mail.

Error Handling

Error handling in Zoho Mail's REST APIs ensures consistent responses when errors occur. Below are key aspects:

HTTP Status Codes

Zoho Mail API uses standard HTTP status codes to indicate the success or failure of a request. 

Example status code and description:

Error Messages

In addition to HTTP status codes, Zoho Mail API returns a JSON response with details about the error. The typical error response format includes:

Example error response:

Rate Limiting

Each Zoho Mail's REST API has its own rate limit, which may vary depending on the specific API. If you exceed the API usage limit, the response will notify you.

By following this guide, you can successfully send your first email via Zoho Mail’s REST API.