SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Send Single Email

Send a single email to a recipient with attachments.

Suggest Edits

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.

  1. 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.
  2. 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" : "<[email protected]>,<[email protected]>", 
   "cc": "<[email protected]>", 
   "bcc": "<[email protected]>", 
   "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": "[email protected]", 
        "from_name": "No Reply Email from Kaleyra", 
        "to": "[email protected]", 
         "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": "[email protected]", 
        "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": "[email protected]",
            "from": "[email protected]",
            "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 [email protected] is provided in the to, cc, and the bcc parameters, the email is sent only once to the [email protected] address with the address shown in the 'to' parameter.
  • If an address [email protected] is provided in both cc and bcc parameters, the email is sent only once to the [email protected] 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": "[email protected]", 
        "from_name": "No Reply Email from Kaleyra", 
        "to": "[email protected]", 
        "cc": "[email protected]", 
        "bcc": "[email protected]", 
         "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": "[email protected]", 
        "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:

ParameterData typeDescriptionExampleMandatory
Yes
fromstringEmail address of the sender“[email protected] ”Yes
tostringRecipient’s email.
In case of multiple recipients separate the address by a comma.		“[email protected]”
or
“[email protected],[email protected],[email protected]”		Yes
ccstringWhen 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 (,).		“[email protected] ” or
“[email protected] ,[email protected] ,[email protected] ”		No
bccstringWhen 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(,).		“[email protected] ” or
“[email protected] ,[email protected] ,[email protected] ”		No
typestringThe 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
subjectstringSubject of the emailSubject for the Email.Yes
from_namestringEmail sender's name“sender”No
dynamic_contentbooleanIf htmlbody or textbody contains dynamic content that needs to be substituted, then set this field 'true'.dynamic_content='true'No
tagstringEmail categoryEmail categoryNo
html_bodystringBody of the email in html."Hello"No
text_bodystringBody of the email in text.“Hello”No
reply_tostringEmail ID to which, the recipient should reply.“[email protected]”No
paramsstringComma separated key-value pair params field.{
“batch”:”b1”, “size”: “15”
}		No
callback_profile_idstringThe callback ID that you have created for email channel with dynamic values.xxxxx_b6d6a697-b3d2-4405-b85e-40027098xxxxNo
refstring/integerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on		campaign nameNo
ref1string/integerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on		customer IDNo
ref2string/integerInclude the contextual information in this parameter.
For Example: Name, Customer ID, and so on		nameNo

Sample Success Response

{
    "data": [
        {
            "message_id": "xxxxxx01-9b7b-xxxx-9c9e-xxx0ae4edxxx:1",
            "to": "[email protected]",
            "cc": "[email protected]",
            "bcc": "[email protected]",
            "from": "[email protected]",
            "subject": "CC AND BCC TESTING"
        }
    ],
    "error": {}
}

📘

Note:

  1. 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.
  1. You can attach files up to a maximum of 20 MB along with the email.
  2. The html body and text body size limits are set to 5 MB each.
  3. 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": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "subject": "Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Hello {{name}}",
  "html_body": "<<b>Hello {{name}}</b>",
  "reply_to": "[email protected]",
  "params": {
              "name":"NAME"              
              }
}

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

{
  "from": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "subject": "Sample Test Email from Email API,Please Ignore!!!! On {{currentdate}}",
  "text_body": "Hello NAME",
  "html_body": "<b>Hello NAME</b>",
  "reply_to": "[email protected]",
  "params": {
              "name":"NAME"              
              }
}

Success Response

The following success message is displayed.

{
    "data": [
        {
            "message_id": "xxxxx207-e525-xxxx-bd44-xxxxxeb8de70:1",
            "to": "[email protected]",
            "from": "[email protected]",
            "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": "[email protected]",
        "from_name": "No Reply Email from Kaleyra",
        "to": "[email protected]",
        "subject": "simple email",
        "text_body": "",
        "html_body": "SMS campaign",
        "reply_to": "[email protected]"
        }'

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": "[email protected]",
        "from_name": "No Reply Email from Kaleyra",
        "to": "[email protected]",
        "subject": "simple email",
        "text_body": "",
        "html_body": "SMS campaign",
        "reply_to": "[email protected]"
        }'

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": "[email protected]",
  "from_name": "sender",
  "to" : "[email protected],[email protected]",
  "subject" : "sample subject",
  "tag" : "invitation",
  "html_body" : "<b>Hello</b>",
  "text_body" : "Hello",
  "reply_to"  : "[email protected]",
  “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": "[email protected],[email protected]",
        	                "from": "[email protected]",
        	                "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": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "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": "[email protected]",
  "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": "[email protected]",
            "from": "[email protected]",
            "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": "[email protected]",
  "from_name": "No Reply Email from Kaleyra",
  "to": "[email protected]",
  "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": "[email protected]",
  "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": "[email protected]",
            "from": "[email protected]",
            "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" : "[email protected]",
"from_name": "Sender Name",
"to": "[email protected]",
"subject": "subject",
"tag": "Sample",
"html_body": "<b>Hello</b>",
"text_body": "Hello",
"reply_to": "[email protected]",
"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 4 months ago

What’s Next