Send Single Email

Send a single email to a recipient with attachments.

The email API allows you to send an email to a recipient using the 'POST' method. In a single email API call, the request body contains only one email content. However, the recipients in the request can be more than one.
You can also have the recipients list added to the 'cc' and the 'bcc' parameters while sending emails.
The recipients in the cc field are visible to all other recipients, and they can also see which other recipients have received the email.
The recipients in the bcc are hidden from all other recipients. The recipients in the To and cc fields cannot see the email addresses in the bcc field. Also, the bcc recipients cannot see other bcc recipients. However, all the bcc recipients can see the ‘to’ list and ‘cc’ list recipients.

📘
Note:
You can add up to 50 email addresses each in the 'to', ‘cc’, and the ‘bcc’ parameters in the email API.
At least one recipient in the ‘to’ field is mandatory.

Base URL

https://api.kaleyra.io/v1/

Send an Email API request

To send an email API request, follow the steps below.

Prerequisites:
1. Create an API key, refer to the Create an API Key page for steps to create your API key.
  To view the API Key and the SID, see View API Key and SID.
2. Get the Email channel enabled for your account by contacting the Kaleyra support team.
  Share the domain name (from email addresses) using which the email must be sent. The domain is then whitelisted by the support team and the email service is enabled.
Send the email API request.

API Request to Send an Email

The following API sends an email to one or more recipients.
To send an email, use the endpoint: https://api.kaleyra.io/v1/><SID>/email

📘
Note:
Make sure to replace the parameters with appropriate values in the API.

Request format

The following is the generic request format to send an email to a recipient in the to, cc, and the bcc list.

curl --location --request POST '<base_url>/email' \ 
-H `api-key: <API_KEY>' \ 
-H `content-type: <content-type >`
-d ‘{ 
   "from": "<from>" 
   "from_name": "<from_name>" 
   "to" : "<recipient@abc.com>,<recipient1@abc.com>", 
   "cc": "<recipient2@abc.com>", 
   "bcc": "<recipient3@abc.com>", 
   "type" : "<type>", 
   "Subject" : "<subject>", 
   "tag" : "<tag>", 
   "html_body" : "<b><html_body></b>", 
   "text_body" : "<text body>", 
   "reply_to"  : "<reply to>" 
   "callback_profile_id": "<callback profile id>", 
   "ref":"<optional parameter>", 
   "ref1":"<optional parameter>", 
   "ref2":"<optional parameter>" 
  }'

Sample API request

The following is a sample API request to send an email to a single recipient.

curl ----request POST 'https://api.kaleyra.io/v1/xxxxx7787xxxxxIN/email' \ 
--header 'api-key: xxxxxe49xxxx13ce3f53613dad5xxxxxx' \ 
--header 'Content-Type: application/json' \ 
--data-raw  
 '{ 
        "from": "no-reply@kaleyra.com", 
        "from_name": "No Reply Email from Kaleyra", 
        "to": "name@abc.com", 
         "tag": "Tag the InvitationTag !!", 
        "subject": "--Test 2 try our Hello campaign test at IN prod from email team", 
        "dynamic_content": true, 
        "template_id":"", 
        "webhook_id":"", 
        "text_body": "Try our campaign builder and send a quick test to the phone number you used during the registration process.", 
        "html_body": "", 
        "reply_to": "replyto@kaleyra.com", 
        "callback_profile_id": "xxxxx_xxxbf18a-bdc2-4a34-a0bd-eea2b1bxxxxx", 
        "ref":"campaign2", 
        "ref1":"companyID", 
        "ref2":"productname", 
        "metadata":  
       { 
            "quantity": "5000", 
            "dMarketValue": "8167.00", 
            "symbol": "PMBND" 
        } 
    }'

Parameters and data types

Refer to the parameter description table given under the section API request to send an email to 'cc' and 'bcc' list, on this page.

Sample Success Response

The following is a sample success response for an email API request with success status 202.

{
    "data": [
        {
            "message_id": "xxxxx02e-507e-xxxx-aed9-xxxf27230c2:1",
             "to": "name@abc.com",
            "from": "no-reply@kaleyra.com",
            "subject": "simple email"
        }
    ],
    "error": {}
}

API request to send an email to 'cc' and 'bcc' list

API request to send an email to 'cc' and 'bcc' list
As an example, the following API request shows how to send an email ‘to’ one recipient, and two recipients in cc and bcc list.

To send an email, use the endpoint: https://api.kaleyra.io/v1/<SID>/email

When you provide the same email address in the 'to,' 'cc,' and the 'bcc,' parameters, the priority is given to 'to' parameter, followed by the 'cc' parameter, and the least priority is given to the 'bcc' parameter.

For example,

If an address xxx@abc.com is provided in the to, cc, and the bcc parameters, the email is sent only once to the xxx@abc.com address with the address shown in the 'to' parameter.
If an address xxx@abc.com is provided in both cc and bcc parameters, the email is sent only once to the xxx@abc.com address with the address shown in the cc parameter.

📘
Note:
You must have at least one recipient name in the ‘To’ list while adding recipients to cc and bcc list in an email request.

Sample API request


 curl --location 'https://api.kaleyra.io/v1/>xxxx176938xxxxxx/email/' \ 
--header 'api-key: xxxxx86ea3bc3d0840a131ae031xxxxxx' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
         "from": "no-reply@kaleyra.com", 
        "from_name": "No Reply Email from Kaleyra", 
        "to": "john.d@example.com", 
        "cc": "jack.m@example.com", 
        "bcc": "liz.c@example.com", 
         "tag": "Tag the InvitationTag !!", 
        "subject": "CC AND BCC TESTING 2", 
        "dynamic_content": true, 
        "template_id":"", 
        "webhook_id":"", 
        "text_body": "", 
        "html_body": "SMS Try our campaign builder and send a quick test to the phone number you used during the registration process. You will be amazed to discover it will only take a few minutes to launch your first campaign Quantity:", 
        "reply_to": "replyto@kaleyra.com", 
        "attachments": [], 
        "metadata": { 
            "quantity": "500", 
            "dMarketValue": "80", 
            "OTP": "PMBND",
            "callback_profile_id": "xxxxx_850bxx8a-bdc2-4axx-a0bd-xxa2b1b176d1", 
        "ref":"campaign2", 
        "ref1":"companyID", 
        "ref2":"productname" 
        } 
    }'

Parameters description table

Below is the list of parameters used in an email API request:

Parameter	Data type	Description	Example	Mandatory
				Yes

from	string	Email address of the sender	“sender@example.com ”	Yes
to	string	Recipient’s email. In case of multiple recipients separate the address by a comma.	“recipient@gmail.com” or “recipient1@example.com,recipient2@example2.com,recipientx@example3.com”	Yes
cc	string	When you send an email on CC (carbon copy) to a recipient, it means that a copy of the email is sent to keep the recipient informed. In case of multiple recipients separate the address by a comma (,).	“recipient@gmail.com ” or “recipient1@example.com ,recipient2@example2.com ,recipientx@example3.com ”	No
bcc	string	When you send an email on BCC (blind carbon copy) to a recipient, it means that a copy of the email is sent to that person. In case of multiple recipients separate the address by a comma(,).	“recipient@gmail.com ” or “recipient1@example.com ,recipient2@example2.com ,recipientx@example3.com ”	No
type	string	The email type. The type can be, 'OTP', 'MKT', and 'TXN'. By default, the type is considered to be 'MKT' even when the parameter is left blank	"TXN"	No
subject	string	Subject of the email	Subject for the Email.	Yes
from_name	string	Email sender's name	“sender”	No
dynamic_content	boolean	If htmlbody or textbody contains dynamic content that needs to be substituted, then set this field 'true'.	dynamic_content='true'	No
tag	string	Email category	Email category	No
html_body	string	Body of the email in html.	"Hello"	No
text_body	string	Body of the email in text.	“Hello”	No
reply_to	string	Email ID to which, the recipient should reply.	“replyTo@example.com”	No
params	string	Comma separated key-value pair params field.	{ “batch”:”b1”, “size”: “15” }	No
callback_profile_id	string	The callback ID that you have created for email channel with dynamic values.	xxxxx_b6d6a697-b3d2-4405-b85e-40027098xxxx	No
ref	string/integer	Include the contextual information in this parameter. For Example: Name, Customer ID, and so on	campaign name	No
ref1	string/integer	Include the contextual information in this parameter. For Example: Name, Customer ID, and so on	customer ID	No
ref2	string/integer	Include the contextual information in this parameter. For Example: Name, Customer ID, and so on	name	No

Sample Success Response

{
    "data": [
        {
            "message_id": "xxxxxx01-9b7b-xxxx-9c9e-xxx0ae4edxxx:1",
            "to": "john.d@example.com",
            "cc": "jack.m@example.com",
            "bcc": "liz.c@example.com",
            "from": "no-reply@kaleyra.com",
            "subject": "CC AND BCC TESTING"
        }
    ],
    "error": {}
}

📘
Note:

The content in the email body is fetched either from the 'html_body' or from the 'text_body' parameters based on, which parameter the email server supports.

Use the html_body parameter when you have to send email to clients that can process html content. Using this parameter, you can send formatted text, links, images, and so on.
With html_body parameter, the 'email tracking' facility is best enabled.

Use the text_body parameter when you have to send email to client that can process the emails only in text format.

When you use both the parameters, the HTML sends text version of the content to the clients that support only text.

You can attach files up to a maximum of 20 MB along with the email.

The html body and text body size limits are set to 5 MB each.

In case you attach a file to your email, be sure that the overall size of the email, i.e. text body + html body + attached file is 20MB. If the overall size is more than 20MB, then an error "Request payload exceeded" is displayed. For more information, see Email error codes page.

API Request Responses

This section shows the success and the failure responses for different scenarios.

Example of an Email API successfully delivered

The following email API request uses dynamic value in the email body using params field.

{
  "from": "no-reply@kaleyra.com",
  "from_name": "No Reply Email from Kaleyra",
  "to": "xxxa@kaleyra.com",
  "subject": "Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Hello {{name}}",
  "html_body": "<<b>Hello {{name}}</b>",
  "reply_to": "replytoEmai@kaleyra.com",
  "params": {
              "name":"NAME"              
              }
}

After replacing dynamic content, the email API is as follows:

{
  "from": "no-reply@kaleyra.com",
  "from_name": "No Reply Email from Kaleyra",
  "to": "xxxa@kaleyra.com",
  "subject": "Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Hello NAME",
  "html_body": "<b>Hello NAME</b>",
  "reply_to": "replytoEmai@kaleyra.com",
  "params": {
              "name":"NAME"              
              }
}

Success Response

The following success message is displayed.

{
    "data": [
        {
            "message_id": "xxxxx207-e525-xxxx-bd44-xxxxxeb8de70:1",
            "to": "xxx@kaleyra.com",
            "from": "no-reply@kaleyra.com",
            "subject": "Staging EU  Sample Test Email from Email API,Please Ignore!!!! On 11/11/2021 13"
        }
    ],
    "error": {}
}

Failure response for invalid SID

The following email API has an invalid SID.

curl --location 'https://api.kaleyra.io/v1/><invalidsid>/email/' \
--header 'api-key: xxxxx86ea3bc3d0840a131ae031xxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
         "from": "no-reply@kaleyra.com",
        "from_name": "No Reply Email from Kaleyra",
        "to": "john.d@example.com",
        "subject": "simple email",
        "text_body": "",
        "html_body": "SMS campaign",
        "reply_to": "replyto@kaleyra.com"
        }'

The following error message is displayed.

{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "record not found"
    }
}

Error response for invalid API key

The following script shows an email API script with an invalid API key.

curl --location 'https://api.kaleyra.io/v1/>xxxx176938xxxxxx/email/' \
--header 'api-key: <invalidapi>' \
--header 'Content-Type: application/json' \
--data-raw '{
         "from": "no-reply@kaleyra.com",
        "from_name": "No Reply Email from Kaleyra",
        "to": "john.d@example.com",
        "subject": "simple email",
        "text_body": "",
        "html_body": "SMS campaign",
        "reply_to": "replyto@kaleyra.com"
        }'

The following error message is displayed.

{
    "code": "RBC201",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "api key details not found in the DB search"
    }
}

Send Email with an attachment

The following API script sends an email to a recipient with URL as an attachment. Make sure that the attachment has an absolute URL or base 64 encoded data in it.

The following email API script sends a URL as an attachment.

{
  "from": "sender@example.com",
  "from_name": "sender",
  "to" : "recipient@gmail.com,recipient1@gmail.com",
  "subject" : "sample subject",
  "tag" : "invitation",
  "html_body" : "<b>Hello</b>",
  "text_body" : "Hello",
  "reply_to"  : "reply@example.com",
  “attachments”: 
[
           {
               “content”: "https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
               “content-type”: ”text/plain”,
               “filename”: “requirements.txt”
           }
]
}

Success response

The following success message is displayed.

{
	"data": [
    	              {
        	                "message_id": "xxxxx561-227f-xxxx-ba57-xxxxxa26c5cb:1",
        	                "to": "recipient@gmail.com,recipient1@gmail.com",
        	                "from": "sender@gmail.com",
        	                "subject": "subject"
    	             }
	],
	"error": {}
}

Send email with encoded text

The following API script sends an email to a recipient with an encoded text in an attachment.

{
  "from": "no-reply@kaleyra.com",
  "from_name": "No Reply Email from Kaleyra",
  "to": "xxx@kaleyra.com",
  "subject": "{{subjectStartsWith}}  Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Sample Text Body",
  "html_body": "!DOCTYPE html><html><body><h1>My First Heading</h1><p>My first paragraph.</p></body></html>",
  "reply_to": "replytoEmai@kaleyra.com",
  "attachments": [
    {
       "content": "aHR0cHM6Ly9yYXcuZ2l0aHViLmNvbS9ub2",
                "content_type": "application/pdf",
                "filename": "solution1.txt"
    }
    
  ],
  "params": { }
}

The following success response message is displayed. In the email attachment, the encrypted text is decoded and the actual value(text) is displayed.

{
    "data": [
        {
            "message_id": "xxxxx3f2-94fd-xxxx-ab06-xxxxx1067811:1",
            "to": "xxx.p@kaleyra.com",
            "from": "no-reply@kaleyra.com",
            "subject": "Staging EU  Sample Test Email from Email API,Please Ignore!!!! On 11/29/2021 12"
        }
    ],
    "error": {}
}

An example of successful Email API with multiple attachments

You can send multiple attachments along with your email.

The following email API script is an example for a request that has one attachment where content is an absolute URL of a resource.

{
  "from": "no-reply@kaleyra.com",
  "from_name": "No Reply Email from Kaleyra",
  "to": "xxx@kaleyra.com",
  "subject": "{{subjectStartsWith}}  Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Sample Text Body",
  "html_body": "!DOCTYPE html><html><body><h1>My First Heading</h1><p>My first paragraph.</p></body></html>",
  "reply_to": "replytoEmai@kaleyra.com",
  "attachments": [
    {
      "content": "aHR0cHM6Ly9yYXcuZ2l0aHViLmNvbS9ub2RlbWFpbGVyL25vZGVtYWlsZXIvbWFzdGVyL0xJQ0VOU0U=",
      "content_type": "application/pdf",
      "filename": "solution.pdf"
    },
    {
       “content”: "https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
               “content-type”: ”text/plain”,
               “filename”: “requirements.txt”
    }
  ],
  "params": {
    }
}

The following success response is displayed. The email is sent to the recipient with two attachments.

{
    "data": [
        {
            "message_id": "xxxxxe3a-7596-47a1-bc50-xxxxxf9b0f9d:1",
            "to": "xxx@kaleyra.com",
            "from": "no-reply@kaleyra.com",
            "subject": "Staging EU  Sample Test Email from Email API,Please Ignore!!!! On 11/29/2021 13"
        }
    ],
    "error": {}
}

Response to failure cases of attachment

The following script is an example of a request that has an invalid attachment. The content is neither absolute URL nor base64 encoded data.

{
"from" : "sender@gmail.com",
"from_name": "Sender Name",
"to": "xxx@kaleyra.com",
"subject": "subject",
"tag": "Sample",
"html_body": "<b>Hello</b>",
"text_body": "Hello",
"reply_to": "reply@example.com",
"attachments" :
[
	{
    	    "content":"asfsvadvsdfsdfsdf",
    	    "content_type": "text/plain",
    	    "filename":"requirements.txt"
	}
],
"params": {}
}

The error message is displayed when an invalid content is added in the attachment.

{
    "error": {
        "code": "E12505",
        "type": "Invalid Input",
        "parameter": "attachment",
        "message": "Attachment content is invalid, only base64 or absolute URL is allowed"
    }
}

For different failure scenarios of invalid attachments with the email, refer to the section Email error codes.

For failure scenarios for invalid values in different parameters of the email API, refer to the section Email error codes.

Updated 6 months ago

What’s Next

Send Single Email

📘
Note:

Base URL

Send an Email API request

API Request to Send an Email

📘
Note:

Request format

Sample API request

Parameters and data types

Sample Success Response

API request to send an email to 'cc' and 'bcc' list

📘
Note:

Sample API request

Parameters description table

Sample Success Response

📘
Note:

API Request Responses

Example of an Email API successfully delivered

Success Response

Failure response for invalid SID

Error response for invalid API key

Send Email with an attachment

Success response

Send email with encoded text

An example of successful Email API with multiple attachments

Response to failure cases of attachment

📘Note:

Base URL

Send an Email API request

API Request to Send an Email

📘Note:

Request format

Sample API request

Parameters and data types

Sample Success Response

API request to send an email to 'cc' and 'bcc' list

📘Note:

Sample API request

Parameters description table

Sample Success Response

📘Note:

API Request Responses

Example of an Email API successfully delivered

Success Response

Failure response for invalid SID

Error response for invalid API key

Send Email with an attachment

Success response

Send email with encoded text

An example of successful Email API with multiple attachments

Response to failure cases of attachment

📘
Note:

📘
Note:

📘
Note:

📘
Note: