Send Batch Emails Using Template

Send a batch of transactional emails to multiple recipients using a pre-created CPaaS template.

Endpoint

post /email/template/batch

Copy full URL

Request URL

https://cpaas.zoho.com/v1.1/email/template/batch Copied!

Request Parameters

- Request Headers

ApiKeyAuthAPI Key

API Key of an agent. Send the header as Authorization: Zoho-enczapikey {apiKey}.
Follow the steps here to generate an API key

- Request Body

application/json

JSON Object

Show Sub-Attributes

ccJSON Array[object]Optional

Array of CC recipient email addresses.

Show Sub-Attributes

email_addressJSON ObjectOptional

Show Sub-Attributes

addressstringOptional

Example

manager@zylker.com

namestringOptional

Example

Manager

template_keystringOptional

Unique key of the email template. Use either template_key or template_alias.

Example

1234567890

bccJSON Array[object]Optional

Array of BCC recipient email addresses.

Show Sub-Attributes

email_addressJSON ObjectOptional

Show Sub-Attributes

addressstringOptional

Example

archive@zylker.com

namestringOptional

Example

Archive

attachmentsJSON Array[object]Optional

Array of file attachments. For each attachment supply EITHER content (inline base64) OR file_cache_key (a key returned by the file-upload API) — the two are mutually exclusive. If both are present, file_cache_key takes precedence and content is ignored. When content is used, name and mime_type are required; when file_cache_key is used, name is optional.

Example

[
  {
    "mime_type": "application/pdf",
    "name": "invoice.pdf",
    "content": "JVBERi0xLjQKJcTl8uXrp... (base64-encoded bytes)"
  },
  {
    "file_cache_key": "ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f",
    "name": "terms.pdf"
  }
]

Show Sub-Attributes

file_cache_keystringOptional

Key of a file previously uploaded via the file-upload API (POST /v1.1/files). Required unless content is provided. Mutually exclusive with content.

Example

ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f

mime_typestringOptional

MIME type of the file. Required when content is used.

Example

application/pdf

namestringOptional

File name shown to the recipient. Required when content is used; optional with file_cache_key.

Example

invoice.pdf

contentstringOptional

Base64-encoded file content. Required unless file_cache_key is provided. Mutually exclusive with file_cache_key.

reply_toJSON Array[object]Optional

Reply-to email address.

Show Sub-Attributes

addressstringOptional

Example

support@zylker.com

namestringOptional

Example

Support

bounce_addressemailOptional

Verified bounce (Return-Path) address that receives bounce notifications for this email. Must be a bounce address created and verified under the sending agent's domain.

Example

bounce@bounce-zem.zylker.com

fromJSON ObjectMandatory

The sender's email address and optional display name.

Show Sub-Attributes

addressstringMandatory

Example

accounts@info.zylker.com

namestringOptional

Example

Paula

track_opensbooleanOptional

Enable or disable open tracking.

Example

true

template_aliasstringOptional

Alias of the email template. Use either template_alias or template_key.

Example

account-confirmation

toJSON Array[object]Mandatory

List of recipients. Each recipient can have individual merge info.

Show Sub-Attributes

email_addressJSON ObjectOptional

Show Sub-Attributes

addressstringOptional

Example

accounts@info.zylker.com

namestringOptional

Example

accounts

merge_infoJSON ObjectOptional

Merge variables specific to this recipient.

Show Sub-Attributes

{key_name}string

Accepts any additional properties with custom keys

track_clicksbooleanOptional

Enable or disable click tracking.

Example

true

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request POST \
  --url https://cpaas.zoho.com/v1.1/email/template/batch \
  --header 'Authorization: Zoho-enczapikey {apiKey}' \
  --header 'content-type: application/json' \
  --data '{"cc":[{"email_address":{"address":"manager@zylker.com","name":"Manager"}}],"template_key":"1234567890","bcc":[{"email_address":{"address":"archive@zylker.com","name":"Archive"}}],"attachments":[{"mime_type":"application/pdf","name":"invoice.pdf","content":"JVBERi0xLjQKJcTl8uXrp... (base64-encoded bytes)"},{"file_cache_key":"ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f","name":"terms.pdf"}],"reply_to":[{"address":"support@zylker.com","name":"Support"}],"bounce_address":"bounce@bounce-zem.zylker.com","from":{"address":"accounts@info.zylker.com","name":"Paula"},"track_opens":true,"template_alias":"account-confirmation","to":[{"email_address":{"address":"accounts@info.zylker.com","name":"accounts"},"merge_info":{"property1":"string","property2":"string"}}],"track_clicks":true}'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) throws Exception{

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://cpaas.zoho.com/v1.1/email/template/batch"))
        .header("content-type", "application/json")
        .header("Authorization", "Zoho-enczapikey {apiKey}")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"cc\":[{\"email_address\":{\"address\":\"manager@zylker.com\",\"name\":\"Manager\"}}],\"template_key\":\"1234567890\",\"bcc\":[{\"email_address\":{\"address\":\"archive@zylker.com\",\"name\":\"Archive\"}}],\"attachments\":[{\"mime_type\":\"application/pdf\",\"name\":\"invoice.pdf\",\"content\":\"JVBERi0xLjQKJcTl8uXrp... (base64-encoded bytes)\"},{\"file_cache_key\":\"ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f\",\"name\":\"terms.pdf\"}],\"reply_to\":[{\"address\":\"support@zylker.com\",\"name\":\"Support\"}],\"bounce_address\":\"bounce@bounce-zem.zylker.com\",\"from\":{\"address\":\"accounts@info.zylker.com\",\"name\":\"Paula\"},\"track_opens\":true,\"template_alias\":\"account-confirmation\",\"to\":[{\"email_address\":{\"address\":\"accounts@info.zylker.com\",\"name\":\"accounts\"},\"merge_info\":{\"property1\":\"string\",\"property2\":\"string\"}}],\"track_clicks\":true}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("cpaas.zoho.com")

payload = "{\"cc\":[{\"email_address\":{\"address\":\"manager@zylker.com\",\"name\":\"Manager\"}}],\"template_key\":\"1234567890\",\"bcc\":[{\"email_address\":{\"address\":\"archive@zylker.com\",\"name\":\"Archive\"}}],\"attachments\":[{\"mime_type\":\"application/pdf\",\"name\":\"invoice.pdf\",\"content\":\"JVBERi0xLjQKJcTl8uXrp... (base64-encoded bytes)\"},{\"file_cache_key\":\"ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f\",\"name\":\"terms.pdf\"}],\"reply_to\":[{\"address\":\"support@zylker.com\",\"name\":\"Support\"}],\"bounce_address\":\"bounce@bounce-zem.zylker.com\",\"from\":{\"address\":\"accounts@info.zylker.com\",\"name\":\"Paula\"},\"track_opens\":true,\"template_alias\":\"account-confirmation\",\"to\":[{\"email_address\":{\"address\":\"accounts@info.zylker.com\",\"name\":\"accounts\"},\"merge_info\":{\"property1\":\"string\",\"property2\":\"string\"}}],\"track_clicks\":true}"

headers = {
    'content-type': "application/json",
    'Authorization': "Zoho-enczapikey {apiKey}"
    }

conn.request("POST", "/v1.1/email/template/batch", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Authorization", "Zoho-enczapikey {apiKey}");
    headersMap.put("Content-Type", "application/json");
    headersMap.put("Accept", "application/json");

    data=Map();
    data_cc=List();
    data_cc_item1=Map();
    data_cc_item1_email_address=Map();
    data_cc_item1_email_address.put("address","manager@zylker.com");
    data_cc_item1_email_address.put("name","Manager");
    data_cc_item1.put("email_address",data_cc_item1_email_address);
    data_cc.add(data_cc_item1);
    data.put("cc",data_cc);
    data.put("template_key","1234567890");
    data_bcc=List();
    data_bcc_item1=Map();
    data_bcc_item1_email_address=Map();
    data_bcc_item1_email_address.put("address","archive@zylker.com");
    data_bcc_item1_email_address.put("name","Archive");
    data_bcc_item1.put("email_address",data_bcc_item1_email_address);
    data_bcc.add(data_bcc_item1);
    data.put("bcc",data_bcc);
    data_attachments=List();
    data_attachments_item1=Map();
    data_attachments_item1.put("file_cache_key","ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f");
    data_attachments_item1.put("mime_type","application/pdf");
    data_attachments_item1.put("name","invoice.pdf");
    data_attachments_item1.put("content","value");
    data_attachments.add(data_attachments_item1);
    data.put("attachments",data_attachments);
    data_reply_to=List();
    data_reply_to_item1=Map();
    data_reply_to_item1.put("address","support@zylker.com");
    data_reply_to_item1.put("name","Support");
    data_reply_to.add(data_reply_to_item1);
    data.put("reply_to",data_reply_to);
    data.put("bounce_address","bounce@bounce-zem.zylker.com");
    data_from=Map();
    data_from.put("address","accounts@info.zylker.com");
    data_from.put("name","Paula");
    data.put("from",data_from);
    data.put("track_opens",true);
    data.put("template_alias","account-confirmation");
    data_to=List();
    data_to_item1=Map();
    data_to_item1_email_address=Map();
    data_to_item1_email_address.put("address","accounts@info.zylker.com");
    data_to_item1_email_address.put("name","accounts");
    data_to_item1.put("email_address",data_to_item1_email_address);
    data_to_item1_merge_info=Map();
    data_to_item1.put("merge_info",data_to_item1_merge_info);
    data_to.add(data_to_item1);
    data.put("to",data_to);
    data.put("track_clicks",true);

    response = invokeUrl
    [
        url: "https://cpaas.zoho.com/v1.1/email/template/batch"
        type: POST
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

Sample Request Body

Copied!

  {
    "cc": [
      {
        "email_address": {
          "address": "manager@zylker.com",
          "name": "Manager"
        }
      }
    ],
    "template_key": "1234567890",
    "bcc": [
      {
        "email_address": {
          "address": "archive@zylker.com",
          "name": "Archive"
        }
      }
    ],
    "attachments": [
      {
        "mime_type": "application/pdf",
        "name": "invoice.pdf",
        "content": "JVBERi0xLjQKJcTl8uXrp... (base64-encoded bytes)"
      },
      {
        "file_cache_key": "ea36f19a.a59e41437e3e1a1.h1.bbeabef0-d2c5-11f1-8876-2a30dd3b833c.1a18258b05f",
        "name": "terms.pdf"
      }
    ],
    "reply_to": [
      {
        "address": "support@zylker.com",
        "name": "Support"
      }
    ],
    "bounce_address": "bounce@bounce-zem.zylker.com",
    "from": {
      "address": "accounts@info.zylker.com",
      "name": "Paula"
    },
    "track_opens": true,
    "template_alias": "account-confirmation",
    "to": [
      {
        "email_address": {
          "address": "accounts@info.zylker.com",
          "name": "accounts"
        },
        "merge_info": {
          "property1": "string",
          "property2": "string"
        }
      }
    ],
    "track_clicks": true
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Show Sub-Attributes

dataJSON Array[object]

Show Sub-Attributes

codestringread-only

Example

EM_104

messagestringread-only

Example

messagestringread-only

Example

request_idstringread-only

Example

req-xxxx

- HTTP code 400

Response Body - application/json

JSON Object

Show Sub-Attributes

dataJSON Object

Show Sub-Attributes

error_codestringread-only

Example

TM_3004

messagestringread-only

Example

Invalid request

messagestringread-only

Example

error

Sample Response: HTTP 200

Copied!

  {
    "data": [
      {
        "code": "EM_104",
        "message": "OK"
      }
    ],
    "message": "OK",
    "request_id": "req-xxxx"
  }

▼ Show full

Sample Response: HTTP 400

Copied!

  {
    "data": {
      "error_code": "TM_3004",
      "message": "Invalid request"
    },
    "message": "error"
  }

▼ Show full