Send Email API

The transmission API lets you to send emails to numerous recipients.

Note: Transmission refers to a campaign. For example, transmission_id means the campaign's unique ID.

Request Type

  • POST

Request URL

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

Content-Type

application/json

List of Request Body Attributes

Parameters

Data Type

Description

transmission_name

String

A user-defined identifier for the transmission (Max length: 150).

recipients

JSON array

An array of recipient objects containing information about who will receive the message. Each object may include merge data and additional metadata.

recipients[].address

String

Email address of the recipient (Max length: 100).

recipients[].nameStringOptional display name associated with the recipient’s address. (Max. length: 100).
recipients[].additional_dataJSON ObjectOptional JSON object containing arbitrary user-defined metadata about the recipient (e.g., phone number, country, or internal identifiers).
recipients[].merge_dataJSON ObjectA JSON object containing key-value pairs used for merge tag substitution in the email subject or content. Keys correspond to merge tags defined in the message, and values replace those tags during rendering.

Example: $[first_name|Customer]$ substitutes first_name or the default value Customer.
recipient_list_idStringID referencing a pre-saved recipient list. When provided, the system loads recipients from the associated list instead of requiring an explicit recipients array in the request payload.
optionsJSON ObjectOptional configuration settings that control email processing and delivery behaviour.
options.open_trackingStringEnables or disables open-tracking for the transmission.
Values: enabled/disabled
Default: enabled
options.click_trackingStringEnables or disables click-tracking for the transmission.
Values: enabled/disabled
Default: enabled
options.schedule_atLongTimestamp (in milliseconds) representing when the message should be scheduled for delivery. If omitted, the message is delivered immediately.
contentJSON ObjectDefines the email content, sender identity, and related rendering rules.
content.fromJSON ObjectSpecifies the sender of the email.
content.from.addressStringRequired email address of the sender (Max length: 100).
content.from.nameStringOptional display name of the sender (Max length: 100).
content.reply_toStringOptional reply-to address. Replies to the email will be directed to this address instead of the sender (Max length: 100).

content.subject

String

Email subject line. Supports merge tags for personalisation. (Max length: 200).

content.html

String

HTML version of the email body. Merge tags within the content are replaced using merge_data.

content.text

String

Plain-text version of the email body. Merge tags are also supported in this field. If content.html node is provided, text need not be specified as it is automatically generated.

content.template_idStringID referencing a pre-saved email template. When provided, the system loads HTML and/or text content from the stored template instead of requiring content.html and content.text fields in the payload.

List of Response Body Attributes

ParametersData TypeDescription
rejected_recipientsIntegerThe count of the recipients rejected by our API. Rejection maybe due to invalid syntax.
accepted_recipientsIntegerThe count of the recipients accepted by our API.
responseJSON ObjectContains the response details of the API.
codeIntegerSuccess or failure code.
messageStringSuccess or failure message returned by the API.
transmission_idStringUnique ID of the transmission.
errorsJSON ArrayContains the error details of the API such as 'code' and 'message'.

Unsubscribe Link

Unsubscribe links can be included in the content using an anchor tag with the attribute data-zcea-unsubcribe="1". Refer to the 'Sample Request Payload for transmission with unsubscribe link' to your right. If you had configured an unsubscribe webhook, it will be called when a contact clicks this link. This webhook will contain the contact details, from which you can get the contact email and add them to your suppression list using our Suppression API.
 

Possible Error Cases

Error Codes

Description

400001

Transmission name not provided.

400002

The recipient list is not provided.

400003

Content details are not provided.

400004

Sender details are not provided.

400005

The sender address is not provided.

400006

Subject is not provided.

400007

Content body is not provided.

400008

Invalid sender address.

400009

The sender domain is not authenticated. Please authenticate your domain before sending emails.

400011

Recipient limit exceeded.

400012CNAME record not verified for bounce domain.

400013

None of the recipients are valid.

400015Your account license has expired. 
400016You do not have sufficient credits to perform this action.
400017Schedule time is lesser than current time.
400024Invalid tracking option.
400025Invalid Reply-To address.
400026Your trial period has ended.
Run in PostmanView Collection

Sample Request Payload for Transmission with inline content

Copied{
 "transmission_name": "hello_customer",
 "recipients": [
   {
     "address": "lucy@example.campaigns.zoho.com",
      "name": "Lucy Girea",
      "additional_data": {
        "phone" : "+919876543210",
        "country": "CA"
     },
     "merge_data": {
       "first_name": "Lucy"
     }
   }
 ],
 "content": {
   "from": {
     "address": "aron@marketing.campaigns.zoho.com",
     "name": "Aron Fletcher"
   },
   "subject": "Hello $[first_name|Customer]$, Welcome to Zylker",
   "html": "<html><body>Welcome $[first_name|Customer]$, your content here!<br></body></html>",
 }
}

Sample Request Payload for Transmission with pre-configured recipient list

Copied{
  "transmission_name": "hello_customer",
  "recipient_list_id": "8000000097065",
  "content": {
    "from": {
      "address": "aron@vnaash.in",
      "name": "Aron Fletcher"
    },
    "subject": "Welcome to Zylker 2",
    "text": "Welcome, $[first_name]$, your content here!"
  }
}

Sample Request Payload for Transmission with template content

Copied{
  "transmission_name": "hello_customer",
  "recipients": [
    {
      "address": "lucy@example.campaigns.zoho.com",
      "additional_data": {
        "phone": "+919876543210",
        "country": "CA"
      },
      "merge_data": {
        "first_name": "Lucy"
      }
    }
  ],
  "content": {
    "from": {
      "address": "aron@vnaash.in",
      "name": "Aron Fletcher"
    },
    "subject": "Welcome to Zylker 2",
    "template_id": "8000000124003"
  }
}

Sample Request Payload for scheduled transmission

Copied{
  "transmission_name": "hello_customer",
  "recipients": [
    {
      "address": "lucy@example.campaigns.zoho.com",
      "name": "Lucy Girea",
      "additional_data": {
        "phone": "+919876543210",
        "country": "CA"
      },
      "merge_data": {
        "first_name": "Lucy"
      }
    }
  ],
  "options": {
    "schedule_at": 1728366058000
  },
  "content": {
    "from": {
      "address": "aron@marketing.campaigns.zoho.com",
      "name": "Aron Fletcher"
    },
    "subject": "Welcome to Zylker",
    "html": "<html><body>Welcome $[first_name|Customer]$, your content here!<br></body></html>"
  }
}

Sample Request Payload for transmission with tracking disabled

Copied{
  "transmission_name": "hello_customer",
  "recipients": [
    {
      "address": "lucy@example.campaigns.zoho.com",
      "name": "Lucy Girea",
      "additional_data": {
        "phone": "+919876543210",
        "country": "CA"
      },
      "merge_data": {
        "first_name": "Lucy"
      }
    }
  ],
  "options": {
    "open_tracking": "disabled",
    "click_tracking": "disabled"
  },
  "content": {
    "from": {
      "address": "aron@marketing.campaigns.zoho.com",
      "name": "Aron Fletcher"
    },
    "subject": "Welcome to Zylker",
    "html": "<html><body>Welcome $[first_name|Customer]$, your content here!<br></body></html>"
  }
}

Sample Request Payload for transmission with unsubscribe link

Copied{
  "transmission_name": "hello_customer",
  "recipients": [
    {
      "address": "lucy@example.campaigns.zoho.com",
      "additional_data": {
        "phone": "+919876543210",
        "country": "CA"
      },
      "merge_data": {
        "first_name": "Lucy"
      }
    }
  ],
  "content": {
    "from": {
      "address": "aron@vnaash.in",
      "name": "Aron Fletcher"
    },
    "subject": "Welcome to Zylker 2",
    "html": "<html><body>Welcome $[first_name|Customer]$, your content goes here <br/><br/> <a href=\"https://zylker.com.com/unsubscribe\" data-zcea-unsubscribe=\"1\" title=\"Unsub\">Unsubscribe</a></body></html>"
  }
}

Sample Request Payload for transmission with reply-to address

Copied{

 "transmission_name": "hello_customer",

 "recipients": [

   {

     "address": "lucy@example.campaigns.zoho.com",

    "name": "Lucy Girea",

    "additional_data": {

    "phone" : "+919876543210",

    "country": "CA"

     },

     "merge_data": {

       "first_name": "Lucy"

     }

   }

 ],

 "content": {

   "from": {

     "address": "aron@marketing.campaigns.zoho.com",

     "name": "Aron Fletcher"

   },

    "reply_to": "aron@reply.campaigns.zoho.com",

   "subject": "Welcome to Zylker",

   "html": "<html><body>Welcome $[first_name|Customer]$, your content here!<br></body></html>",

 }

Sample Response - Success

Copied{
   "rejected_recipients": 1,
   "accepted_recipients": 1,
   "response": {
       "code": 200001,
       "message": "Your transmission has been scheduled successfully"
   },
   "transmission_id": "146429000000058021"
}

Sample Response - Failure

Copied{
   "errors": [
       {
           "code": 400012,
           "message": "CNAME not verified for bounce domain"
       },
       {
           "code": 400009,
           "message": "Sender domain not authenticated. Please authenticate your domain before sending"
       }
   ]
}