Templates API - Single Email

You can use this API to send emails using templates. Refer to the Templates help documentation to see how you can create templates and to see which API is suitable for you. 

Table of Contents

Pre-requisite:

You will require a Send Mail token and the Reference ID of the template you wish to use while sending emails via this API.

Steps to generate Send mail token:

  1. Navigate to the Mail Agents tab on the left panel of your ZeptoMail account and select a Mail Agent that you want to connect to your application.
  2. On the top right section, click on Setup Info (gear icon). This will open the Setup Details page.
  3. From here you can copy your Mail Agent specific send mail token under the API tab.
  4. You can use the default Send Mail Token or generate a new one.
  5. You need to add this Send Mail Token to your API header. This authorises your identity.

Steps to copy Template ID:

  1. Navigate to the Mail Agents tab on the left panel of your ZeptoMail account and select the Mail Agent. 
  2. Hover to the Templates tab.
  3. Choose the template you wish to use from the pre-existing templates or create a new template.
  4. Copy the template ID of your template using the copy icon.
  5. You have to paste this ID in the body of your code. 

Sending a single email using Templates

Purpose

This API is used to send transactional emails using templates. It can be used to send one email at a time using the template.

Request URL

https://api.zeptomail.com/v1.1/email/template

Authorization token

You need to add send mail token to authenticate your API requests. This is a unique token that you can generate within your Mail Agent in your ZeptoMail account. Use the send mail token as a header when you call ZeptoMail REST Email Sending API.

Example

POST /v1.1/email/template

Query String:

Method: POST
HOST: https://api.zeptomail.com/v1.1/email/template
Header:
Authorization: zoho-enczapikey <space> <send mail token>

Note:

You can scroll down the sample code section of this page to view the sample request and sample response.

Request Body

* - Mandatory parameters

Parameter Data TypeDescription
template_key*/
template_alias		 String

Unique key identifier for your template.
template_alias is the alias name given to the template key. It can be used in the place of template_key.​

bounce_address String

The email address to which bounced emails will be sent.

Allowed value - A valid bounce email address as configured in your Mail Agent.

from* JSON object

Allowed value - A valid sender email address with "address" and "name" key-value pairs

 addressString

A valid email address containing a domain that is verified in your Mail Agent.

 nameString

Sender's name.

to* JSON arrayAllowed value - JSON object of email_address.
         email_addressJSON object

A valid recipient email address with "address" and "name" key-value pairs.

          addressString

Recipient's email address field.

          nameString

Recipient's name.

merge_info* JSON object

You can use merge tags to replace the placeholders with multiple values for different recipients. The merge tags of the mail to be sent. Merge Tags can be set in HTML body, text body, subject and client reference.

Merge tags are tags that are set in the string.

These tags will be replaced by the value provided in this param for that tag.

In the case of single email API, the merge tag is common for all recipients. Whereas in the case of batch emails, the merge tag is specific to each recipient.

reply_to JSON array

Allowed value - JSON object of reply_to email addresses.

          addressString

The email address to which the recipient's email responses will be addressed.

Allowed value - A valid email address containing a domain that is verified in your Mail Agent.

          nameString

Name for the reply-to parameter.

track_clicks Boolean

You can enable or disable email click tracking here.

You can also enable email click tracking in your Mail Agent under Email Tracking section.

Note: The API setting will override the Mail Agent settings in your ZeptoMail account. 

Allowed value 

True - Enable email click tracking.

False - Disable email click tracking.

track_opens Boolean

You can enable or disable email open tracking. 

You can also enable email open tracking in your Mail Agent under Email Tracking section.

Note: The API setting will override the Mail Agent settings in your ZeptoMail account. 

Allowed value 

True - Enable email open tracking.

False - Disable email open tracking.

client_reference String

An identifier set by the user to track a particular transaction.

mime_headers JSON object

The additional headers to be sent in the email for your reference purposes.

attachments JSON array

The attachments you want to add to your transactional emails. Click here to view the list of unsupported formats. 

Allowed value - JSON object of attachments. 

 It can either be a base64 encoded content or file_cache_key or both.

          contentString

The content of your attachment.

Allowed value - Base64 encoded value of a file.

          mime_typeString

Indicates the content type in your attachment. 

Allowed value 

 simple text message - plain / text  

image file - image / jpg

          name 

The file name of your attachment.

          file_cache_keyString

The unique key for your attached files in a Mail Agent.

Obtain file_cache_key from the File Cache section in your Mail Agent.

 nameString

The file name of your attachment as in the File Cache section in your Mail Agent.

Obtain file name from the File Cache section in your Mail Agent. 

          cid String

the content id used by html body for content lookup. Each content should be given a separate cid value. 

Allowed value

It can either a base64 encoded content or a file_cache_key or both.

Success Response Parameters 

ParameterData TypeDescription
dataJSON arrayIt consists of code, additional_info and message parameters
codeStringThe code corresponding to a success response
additional_infoJSON arrayProvides additional information about the action performed in the request
messageStringThe action taken for this request
messageStringThe status of the request made
request_idStringA unique id which is generated for every request
objectEmailIt signifies that the response is for email API

Failure Response Parameters

ParameterData TypeDescription
errorJSON objectIt consists of code, details, message, and request_id parameters
codeStringThe code corresponding to the status of the request made
detailsJSON arrayIt consists of code, message and target parameters
target_valueStringA unique id which is generated for every request
codeStringThe code for the error found
messageStringReason for the error
targetStringThe field that caused the error
messageStringThe status of the request made

HTTP status codes

Status code

Description
2xxSuccess
4xx

Failure.

Action needed at the user end to fix the error.

5xx

Failure.

Action needed at ZeptoMail server to fix the error.

Error Codes

Note:

Before you get started it is important to know that ZeptoMail is for sending transactional emails like welcome emailers, password resets emails, OTPs. We do not support sending of bulk emails or promotional emails like newsletters or marketing campaign emails. If you are looking for a bulk email provider, you can visit Zoho Campaigns.

Sample Request

Copiedcurl "https://api.zeptomail.com/v1.1/email/template"\
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization:Zoho-enczapikey ***" \
-d {
    "template_key": "ea36f19a.2bec9ad9c994ee6f.k1.7207ab80-da56-11eb-850c-525400256d50.17a6198be38",
    "bounce_address": "bounce@bounce.zylker.com",
    "from": {
        "address": "rebecca@zylker.com",
        "name": "Rebecca"
    },
    "to": [
        {
            "email_address": {
                "address": "paula@zylker.com",
                "name": "Paula M"
            }
        },
        {
            "email_address": {
                "address": "charles@zylker.com",
                "name": "Charles"
            }
        }
    ],
    "cc": [
        {
            "email_address": {
                "address": "tucker@zylker.com",
                "name": "Tucker"
            }
        },
        {
            "email_address": {
                "address": "vienna@zylker.com",
                "name": "Vienna"
            }
        }
    ],
    "bcc": [
        {
            "email_address": {
                "address": "priya@zylker.com",
                "name": "Priya"
            }
        },
        {
            "email_address": {
                "address": "Selena@zylker.com",
                "name": "Selena"
            }
        }
    ],
             "merge_info": {
                  "meeting_link":"https://meeting.zoho.com/join?key=103666049*************22c92ca4"
    },
    "reply_to": [
        {
            "address": "rebecca@zylker.com",
            "name": "Rebecca"
        }
    ],
    "client_reference": "1234",
    "mime_headers": {
        "X-Test": "test"
    }
}'

Sample Response

Copied{
  "data": [
    {
      "code": "EM_104",
      "additional_info": [],
      "message": "Email request received"
    }
  ],
  "message": "OK",
  "request_id": "ea36f19a.2bec9ad9c994ee6f.m1.cc7d93d0-e966-11eb-95aa-525400ada42a.17ac451bd8d",
  "object": "email"
}