Authentication

CPaaS APIs support two authentication mechanisms. Email management APIs (email sending, file upload), Voice, SMS, and WhatsApp use an API key. Other APIs such as Agents, Templates, Email logs, Suppressions, and Domains use Zoho OAuth 2.0.

If you make an API request without the correct authorization header, CPaaS will return an HTTP 401 Unauthorized error.

API Key

The API key authenticates all email sending, Voice, SMS, and WhatsApp API requests for transactional communications. This token is unique to each Agent. Separate keys are generated for each communication channel within the same Agent.

Generate an API key

Follow the steps to generate the API key.

Select the Agent you want to connect to your application.
Navigate to the SMTP/API tab. This will open the API Setup page.
In the API Setup page, you will find your Agent-specific API key.
You can either copy the default API key or generate a new one.

Agents >> {Agent_name} >> SMTP/API tab >> API Setup >> Agent key >> Click to copy icon

Note-
The SMS feature is currently supported for customers hosting their accounts in the IN DC. You can send transactional SMS from your registered sender to customers in India.

Use the API key in a request

Add the API key to the Authorization header with the prefix Zoho-enczapikey.

Authorization: Zoho-enczapikey REPLACE_WITH_YOUR_KEY

Example request:

Copiedcurl --request POST \
  --url https://cpaas.zoho.com/v1.1/email \
  --header 'Authorization: Zoho-enczapikey REPLACE_WITH_YOUR_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "from": { "address": "hello@yourapp.com", "name": "Your App" },
    "to": [{ "email_address": { "address": "user@example.com", "name": "User" } }],
    "subject": "Your OTP is 482910",
    "htmlbody": "<p>Your one-time code is <b>482910</b>. It expires in 10 minutes.</p>"
  }'

OAuth 2.0

OAuth 2.0 is an industry standard protocol which allows you to grant a third-party website or an application (i.e., a client) delegated access to the protected resources of Zoho via Zoho APIs. It is a way to authenticate and authorize API requests made to Zoho.

Refer to the OAuth 2.0 glossary section to understand more about the terms used here.