Send Single Email

Send a personalized email with one or more attachments.

The email API allows you to send one or more emails to multiple contacts using the 'POST' method.

📘

Base URL

<https://api.kaleyra.io/v1/><SID>/email

Signup or Login to Kaleyra.io and create 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.

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.

curl -X POST https://api.kaleyra.io/v1/<SID>/email/
-H ‘api-key: <API_KEY>' \
-H ‘content-type: application/json’ 
-d ‘{
   "from": "[email protected]"
   "from_name": "sender"
   "to" : "[email protected],[email protected]",
   "type" : "TXN",
   "Subject" : "sample subject",
   "tag" : "invitation",
   "html_body" : "<b>Hello</b>",
   "text_body" : "Hello",
   "callback_profile_id": "IN_453d2677-2c91-4610-9c01-eefbeec5f697"
   "reply_to"  : "[email protected]"
   "params"  :  {}
}
Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "data": [
      {
          "message_id": "123e4567-e89b-12d3-a456-426655440000",
          "to": "[email protected],[email protected]",
          "from": "[email protected]",
          "subject":"subject use in the request"
      }
      
    ],
    "error": {}
}

Parameters and Variables

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

ParameterData typeDescriptionExampleMandatory
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
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
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.IN_453d2677-2c91-4610-9c01-eefbeec5f697No

📘

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 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": "f5542207-e525-45b5-bd44-a40cceb8de70: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 -X POST https://api.kaleyra.io/v1/invalid-sid/email/
-H ‘api-key: valid api key’\
-H ‘content-type: application/json’ 
-d ‘{
   "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]"
   "params"  :  {}
}

The following error message is displayed.

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

Error response for invalid API key

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

curl -X POST https://api.kaleyra.io/v1/valid-SID/email/
-H ‘api-key: xxxxxinvalid-ap-keyxxxxxx’\
-H ‘content-type: application/json’ 
-d ‘{
   "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]"
   "params"  :  {}
}’

The following error message is displayed.

{
    "code": "RBC201",
    "message": "Incorrect SID or API key.",
    "error": {
        "body": "Incororrect SID or API key."
    },
    "data": []
}

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": "c8264561-227f-475c-ba57-2fb38a26c5cb: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": "aHR0cHM6Ly9yYXcuZ2l0aHViLmNvbS9ub2RlbWFpbGVyL25vZGVtYWlsZXIvbWFzdGVyL0xJQ0VOU0U=",
                "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": "7cbc53f2-94fd-43c2-ab06-50bb21067811: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": "64702e3a-7596-47a1-bc50-fa4bbf9b0f9d: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.