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]",
   "Subject" : "sample subject",
   "tag" : "invitation",
   "html_body" : "<b>Hello</b>",
   "text_body" : "Hello",
   "reply_to"  : "[email protected]"
   "metadata"  :  {}
}
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:

Parameter

Data type

Description

Example

Mandatory

from

string

Email address of the sender

[email protected]

Yes

to

string

Recipient’s email.
In case of multiple recipients separate the address by a comma.

[email protected].com”
or
[email protected],[email protected],[email protected]

Yes

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_contntet='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.

[email protected]

No

metadata

string

Comma separated key-value pair metadata.

{
“batch”:”b1”, “size”: “15”
}

No

📘

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 10 MB along with the email.

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 a metadata.

{
  "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]",
  "metadata": {
              "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]",
  "metadata": {
              "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]"
   "metadata"  :  {}
}

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]"
   "metadata"  :  {}
}’

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"
    }
    
  ],
  "metadata": { }
}

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”
    }
  ],
  "metadata": {
    }
}

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"
    }
],
"metadata": {}
}

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.


Did this page help you?