Email Sending API

Purpose

The API is used to send transactional emails.

Request URL

https://api.transmail.com/v1.1/email

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 TransMail account. Use the send mail token as a header when you call TransMail REST Email Sending API.

Example

POST /v1.1/email

Query String:

POST
HOST: https://api.transmail.com
Header:
Authorization: zoho-enczapikey <space> <send mail token>

Steps to generate Send mail token:

  1. Navigate to the Mail Agents tab on the left panel of your TransMail account and select a Mail Agent that you want to connect to your application.
  2. On the top right section, click on Setup Details (gear icon). This will open the Setup Details page.
  3. From here you can copy your Mail Agent specific send mail token from the Send Mail Token(s).

Mail Agents >> Setup Details >> Send Mail Token >> Copy key

Request Body

* - Mandatory parameters

ParameterData TypeDescription
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.

reply_toJSON 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.

subject*String

The subject of the email to be sent.

textbody / htmlbodyString

This is the body content for your email.

Allowed value

Your email body can either be a textbody or a htmlbody.

ccJSON array

Email addresses of cc'd recipients.

Allowed value - JSON object of email_address.

bccJSON array

Email addresses of bcc'd recipients.

Allowed value - JSON object of email_address.

track_clicksBoolean

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 TransMail account. 

Allowed value 

True - Enable email click tracking.

False - Disable email click tracking.

track_opensBoolean

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 TransMail account. 

Allowed value 

True - Enable email open tracking.

False - Disable email open tracking.

client_referenceString

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

mime_headersJSON object

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

attachmentsJSON array

The attachments you want to add to your transactional emails.

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 - img / 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. 

inline_imagesJSON array

This is the Inline image added to your email. 

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

The base64 content contains mime_type, content and cid parameters.

          cidString

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
codeStringThe code for the error found
messageStringReason for the error
targetStringThe field that caused the error
messageStringThe status of the request made
request_idStringA unique id which is generated for every request

HTTP status codes

Status code

Description
2xxSuccess
4xx

Failure.

Action needed at the user end to fix the error.

5xx

Failure.

Action needed at TransMail server to fix the error.

Error Codes

Error CodeReasonSolution
TM_3201Mandatory Field was set as EmptyValue. The mandatory fields are from, to, and subject.  Set the Mandatory Fields as proper values instead of setting Empty in the API.

Note:

The same error responses will be thrown when setting mandatory fields such as subject, to, cc, cc, mime-type in attachments, reply_to, FileCache Key as empty and the empty Field will be shown in target field in the response message. 
TM_3501Invalid FileCache Key 

Obtain proper FileCache Key from the respective Mail Agent in your File Cache tab. 

TM_4001Invalid values 

A) Sendmail token is invalid. Obtain proper Sendmail token from the configuration settings within your Mail Agent. 

B) For invalid Bounce Address, make sure the bounce address you are trying to use here is listed in the bounce setup of TransMail on the respective Mail Agent.

C) For invalid email address other than Bounce Address, verify whether you are using proper Email Address in from, to, bcc, reply_to and cc.

D) Names of the recipients should not be set in the email fields.

Note:

target_value in the error response shows the field where an invalid email address is set. 

TM_8001Exceeding Limits

A) Attachment filename exceeding the limit. Allowed filename limit < = 150. 

B) Attachment size exceeding the limit. Allowed attachment size < = 15 MB. 

C) Total number of attachments exceeding the limit. Allowed total number of attachments < = 60. 

D) Subject field exceeding the character count limit. Allowed subject line character count < = 500.

E) Total number of addresses exceeding the limit. The allowed number for each of these fields are:

     i) reply_to  < = 20

     ii) to           < = 340

     iii) cc         < = 70

     iv) bcc       < = 70

F) Limit exceeded for the name field for any of these parameters - from, to, reply_to, cc, bcc. Allowed limit < = 250.

Note:

target_value in the error response shows the field where the limit is exceeded.

Curl Request details


				"https://api.transmail.com/v1.1/email" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization:Zoho-enczapikey ***" \
-d {"
bounce_address:bounces@info.zylker.com,
from: { 'address': 'accounts@info.zylker.com',  'name': 'Paula'},
to: [{'email_address': {'address': 'rudra.d@zylker.com','name': 'Rudra'}}],
subject:Account Confirmation,
htmlbody:'<div><b> Kindly click on Verify Account to confirm your account </b></div>'}"			

Sample Input

This is a Sample API JSON Format


				{
"bounce_address": "bounces@info.zylker.com",
"from": 
  {
  "address": "accounts@info.zylker.com",
  "name": "Paula"
  },
"to": 
  [
    {
    "email_address": 
      {
      "address": "rudra.d@zylker.com",
      "name": "Rudra"
      }
    } 
  ],
"reply_to": 
  [
      {
      "address": "rudra.d@zylker.com",
      "name": "Rudra"
      } 
  ],
"subject": "Account Confirmation",
"textbody": "Kindly click on Verify Account to confirm your account",
"htmlbody": "<html><body>Hi, Verify your account to start receiving reports<img src=\"cid:img-welcome-design\">scdjsncj<img src=\"cid:img-CTA\"><h1><a href=\"http://www.zylker.com/cache-bin\">Verify Account</a></h1></body></html>",
"cc": 
  [
    {
    "email_address": 
      {
      "address": "rebecca@zylker.com",
      "name": "Rebecca"
      }
    }
  ],
"bcc": 
  [
    {
    "email_address": 
      {
      "address": "helen@zylker.com",
      "name": "helen"
      }
    }
  ],
"track_clicks": true,
"track_opens": true,
"client_reference": "83783/8369423/2882",
"mime_headers": 
  {
  "X-Zylker-User": "rebecca-72893"
  },
"attachments": 
  [
    {
    "content": "..x+SEXa3zKfnDnBA2qExtXikBpUAFABQAhGSPY/0IoAWgD/2Q==",
    "mime_type": "img/jpg",
    "name": "DM-welcome-guide"
    },
    {
    "file_cache_key": "ea36f19a.37b62c9.h1.dd2cb7e0-337f-11ea-afc1-7e55a3f36c77.16f8e7bf1b8",
    "name": "DM-reports"
    }
  ],
"inline_images": 
  [
    {
    "mime_type": "img/jpg",
    "content": "...x+SEXa3zKfnDnBA2qExtXikBpUAFABQAhGSPY/0IoAWgD/2Q==",
    "cid": "img-welcome-design"
    },
    {
    "file_cache_key": "ea36f19a.37b62c9.h1.f20ca6c0-337f-11ea-afc1-7e55a3f36c77.16f8e7c7afb",
    "cid": "img-CTA"
    }
  ]
}			

Sample Success Response


				{
"data":
  [
    {
    "code": "EM_101",
    "additional_info": [],
    "message": "Email queued"
    }
  ],
"message": "OK",
"request_id": "d7624ab4.7a1fa6.i1.83b51de0-56d1-11ea-a70b-4ad472469664.17075f34ebe",
"object": "email"
}			

Sample Failure Response


				{
"error": 
  {
  "code": "TM_4001",
  "details": 
    [
    {
    "code": "SM_113",
    "message": "Invalid email address",
    "target": "bounce_address"
    }
  ],
"message": "Access Denied",
"request_id": "ea36f19a.37b62c9.m1.83fdb210-56f1-11ea-bcae-863166d285e5.17076c507b1"
  }
}