API Authentication

The email API uses the OAuth protocol to provide authentication to access our API functions. This document will explain how this version works in detail.

These are the major advantages of using this OAuth version :

  • The access token has a limited lifetime. Only a developer who has completed the authentication process and has a refresh token will be able to generate a new access token. This way, we can be sure that the access token cannot be misused.

  • The access token is obtained by specifying the scope required for a particular action. This restricts access to only what is actually required and prevents any additional actions from being performed.

  • All JSON parameters in the request should be encoded for enhanced security.

Prerequisites  

  • You should be a client registered in Zoho Accounts. Click here to learn how to register as a client.

Generation of access and refresh tokens  

The most important step in using this version is you must generate access and refresh tokens before you can start using the API.

  1. Using your registered client, send an authorization request to Zoho Accounts. You have to include the necessary scopes for which you require access in this request.

  2. Zoho Accounts will forward this request to the corresponding account owner.

  3. The owner will verify this request and grant permission/access to the requested scopes.

  4. As an acknowledgement of the granted request, Zoho Accounts will send a grant code to you.

  5. Using this grant code, you can request for access token from Zoho Accounts.

  6. Access and refresh tokens will be generated and sent to you. With the help of an access token, you can now use this OAuth version's Email APIs.

Note :

  • Scope: ZohoCampaigns.campaign.ALL

  • You need to follow this cycle every time you need access and refresh tokens.

  • Access tokens expire after one hour. If an access token expires, developers can use the refresh token to generate a new access token.

Calling an API  

Once you've generated access and refresh tokens, you can start making API calls. To call an API, you must paste your access token in the header section.

  • Header: Authorization: Zoho-oauthtoken <access_token>

  • API Root Endpoint: https://campaigns.zoho.com/emailapi/v1/

  • Content-Type: application/json

Sample request  

No access-related entities are used in Email API requests in this version. The API call to send email in this API version is below.

JSON

https://campaigns.zoho.com/emailapi/v1/transmission