Send Batch and Bulk Emails

Send batch and bulk emails with attachments.

You can send 'batch' and 'bulk' emails to recipients using a single API request.

In a 'batch' email request, you can send emails to one or more recipients in a single email request. The email recipients can see all the other recipient names to whom the email is sent. You can send different emails(different email body) to the recipients in the same email request.

In a 'bulk' email request, you can send emails to multiple recipients with the same content; however, the ‘to’ list recipients cannot see the other ‘to’ list recipients.

You can have the recipients list added to the 'cc' and the 'bcc' parameters in both batch and the bulk email requests.

In a batch email with ‘to’, ‘cc’, and ‘bcc’ list, or for every individual email,

  • The recipients in the ‘to’ parameter list can see all the other recipients in the ‘to’ list and the ‘cc’ list.
  • The recipients in the ‘cc’ parameter can see the ‘to’ list, ‘cc’ list.
  • The recipients in the ‘bcc’ parameter can see the ‘to’, ‘cc’ list recipients but NOT the other ‘bcc’ list recipients.

In a bulk email with ‘to’, ‘cc’, and ‘bcc’ lists recipients,

  • The recipients in the ‘to’ list can see only their address in the ‘to’ list, and all the recipients in the ‘cc’ list but not the other recipients in the ‘to’ list. For each recipient in the ‘to’ list, an email is sent to the ‘to’ recipient and all the ‘cc’, ‘bcc’ recipients.
  • The recipients in the ‘cc’ list see one ‘to’ recipient and all the other ‘cc’ list recipients.
  • The recipients in the ‘bcc’ list see on ‘to’ recipient and ‘cc’ list recipients but not the other ‘bcc’ list recipients.

📘

Note:

You can add up to 50 email addresses each of the 'to', ‘cc’, and the ‘bcc’ parameters in an email API.

Send batch emails

Use 'batch email', to send emails to different groups of recipients with different content using a single API.

Use the endpoint: https://api.kaleyra.io/v1/<SID>/email/batch.

Base URL

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

Request format

The following is the request format for batch email API request.

curl -X POST '<url>/api/v1/<sid>/email/batch' \
--header 'api-key: <API KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  		“From”: “<from>”
  		“from_name”: “<from_name>”
  		“to” : “<to>”,
       "cc":   "<cc>"
     		“Subject” : “Sample subject”,
  		“tag” : “<tag>”,
  		“html_body” : “<html_body>”,
  		“text_body” : “<text_body>”,
  		“reply_to”  : “<[email protected]>”
  		},
            {
  		“from”: ”<from>”
  		“from_name”: “<from_name>”
  		“to” : “<to>”,
       "cc":   "<cc>"
  		“Subject” : “<sample subject>”,
  		“tag” : “<tag>”,
  		“html_body” : “<html_body>”,
  		“text_body” : “<text_body>”,
  		“reply_to”  : “<[email protected]>” 
             }'
            }

Sample API Request

The following API sends emails to multiple recipients in To and CC parameters using the POST method in a batch email request.

curl --location --request POST 'https://api.kaleyra.io/v1/xxxxx71022xxxxx/email/batch' \
--header 'api-key: xxxxxada1bd635aadb5c7316a08xxxxxx' \
--header 'Content-Type: application/json' \

--data-raw '[
    {
        "from": "[email protected]",
        "from_name": "No Reply Email from Kaleyra",
        "to" : "[email protected],[email protected]", 
      	"cc":  "[email protected]", 
        "subject": "Sample Test1 Email from Email API",
        "text_body": "",
        "html_body": "SMS Try our campaign module.",
        "tag": "Tag the InvitationTag !!",
        "reply_to": "[email protected]"
        
    },
   {
        "from": "[email protected]",
        "from_name": "No Reply Email from Kaleyra",
	      "to" : "[email protected],[email protected]",
	      "cc":  "[email protected]",
        "subject": "Sample Test2 Email from Email API",
        "text_body": "",
        "html_body": "SMS Try our campaign builder.",
        "tag": "Tag the InvitationTag !!",
        "reply_to": "[email protected]"
        
    }

]'

📘

Note:

For parameters description, refer to the parameter table description in the section: Parameter Description Table.

Success response

The following success response is displayed.

{
    "data": [
        {
            "message_id": "891b3008-d330-448f-a827-a768c47dd54c:1",
            "to": "[email protected],[email protected]",
            "cc": "[email protected]",
            "from": "[email protected]",
            "subject": "Sample Test1 Email from Email API"
        },
        {
            "message_id": "891b3008-d330-448f-a827-a768c47dd54c:2",
            "to": "[email protected],[email protected]",
            "cc": "[email protected]",
            "from": "[email protected]",
            "subject": "Sample Test2 Email from Email API"
        }
    ],
    "error": []
}

Request for multiple emails with one invalid request

[
  {
  		“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”  :{"Model”:”Volkswagen”, “Client-Id”:”786"}
  },
  {
  		“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”  : {"Model”:”Volkswagen”, “Client-Id”:”786"}
  },
 {
  		“from”: ”[email protected]”
  		“from_name”: “sender”
  		“to” : “[email protected] ,aaa,[email protected]”,
  		“Subject” : “sample subject”,
  		“tag” : “invitation”,
  		“html_body” : “<b>Hello</b>”,
  		“text_body” : “Hello”,
  		“reply_to”  : “[email protected]”
  }
]

For the emails that are successfully delivered, a success response is displayed. For the emails that are not sent, an error message is displayed.

The success and the error messages are displayed as follows:

[
  {
  		“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”  :{"campaign”:”christmas”, “Client-Id”:”786"}
  },
  {
  		“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”  : {"Model”:”Volkswagen”, “Client-Id”:”786"}
  },
 {
  		“from”: ”[email protected]”
  		“from_name”: “sender”
  		“to” : “[email protected] ,aaa,[email protected]”,
  		“Subject” : “sample subject”,
  		“tag” : “invitation”,
  		“html_body” : “<b>Hello</b>”,
  		“text_body” : “Hello”,
  		“reply_to”  : “[email protected]”
  }
]

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": 
    [
      {
          "message_id": "123e4567-e89b-12d3-a456-426655440001",
          "to": "[email protected],[email protected]",
          "from": "[email protected]",
          "subject":"sample subject"
      },
      {
          "message_id": "123e4567-e89b-12d3-a456-426655440003",
          "to": "[email protected],[email protected]",
          "from": "[email protected]",
          "Subject":"sample subject"
      }
    ],
    "error": 
    [ {
	"code": "E12501",
	"type": "Invalid input",
	"parameter": "to",
            "message": "The value [ [email protected] ,aaa,[email protected]] for to parameter is invalid. ",
	"reference": ""
}
    ]
}

Email API with multiple requests and multiple attachments

The following email API example has multiple email requests and multiple attachments in each request.

[
{
"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":"https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
    	   "content_type": "text/plain",
    	   "filename":"requirements.txt"
	},
    	{
    	   "content":"https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
    	   "content_type": "text/plain",
    	   "filename":"requirements.txt"
	}
],
           "params": {}
},
{
"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":"https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
    	   "content_type": "text/plain",
    	   "filename":"requirements.txt"
	},
    	{
    	   "content":"https://github.com/kaleyra/kaleyra-python/blob/master/requirements.txt",
    	   "content_type": "text/plain",
    	   "filename":"requirements.txt"
	}
],
"params": {}
}
]

The following example success response is displayed.

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


{
	"data": [
    	{
        	   "message_id": "a84fa56e-3be8-49ad-9fd9-eb8454b452f3:1",
        	   "to": "[email protected],[email protected]",
        	   "from": "[email protected]",
        	   "subject": "subject"
    	},
    	{
        	   "message_id": "a84fa56e-3be8-49ad-9fd9-eb8454b452f3:2",
        	   "to": "[email protected],[email protected]",
        	   "from": "[email protected]",
        	   "subject": "subject"
    	}
	],

	"error": []
}

Send bulk emails

In a bulk email API, you can send the same email content to multiple recipients using a single email API request. Each individual recipient, even if included in 'to', 'cc', or 'bcc' receives an email addressed only to the recipient.

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

Base URL

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

Request format

The following is the request format for bulk email API.

curl -X POST '<url>/api/v1/<sid>/email/bulk' \
--header 'api-key: <api>' \
--header 'Content-Type: <content type>' \
 --data-raw '{
  		“from”: ”[email protected]”
  		“from_name”: “sender”
  		“to” : “[email protected],[email protected]”,
      "cc" : "[email protected]",
      "bcc": "[email protected]",  
  		“Subject” : “sample subject”,
  		“tag” : “invitation”,
  		“html_body” : “<message body>”,
  		“text_body” : “<message body>o”,
  		“reply_to”  : “[email protected]”
  }'

Sample API request

The following is a sample bulk email API request.

Every individual recipient in the to, cc, and the bcc list receives an email addressed only to them and cannot view other recipients' addresses.

curl --location --request POST 'https://api.kaleyra.io/v1/xxxxx71022xxxxx/email/bulk' \
--header 'api-key: xxxxxada1bd635aadb5c7316a08xxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
        "from": "[email protected]",
        "from_name": "no reply EMAIL",
        "to": "[email protected],[email protected]",
        "cc": "[email protected]",
        "bcc": "[email protected]",
        "subject": "Bulk email from Email API",
        "text_body": "",
        "html_body": "Try our SMS campaign builder",
        "reply_to": "[email protected]"
        }'

📘

Note:

Refer to the parameter description table in the section, Parameter Description Table

Success response

Each individual recipient receives an email addressed only to respective recipient and cannot view other recipients' addresses.

{
    "data": [
        {
            "message_id": "ccde552d-43da-4f03-89bd-88860a7940ac:1",
            "to": "[email protected]",
            "cc": "[email protected]",
            "bcc": "[email protected]",
            "from": "[email protected]",
            "subject": "Bulk email from Email API"
        },
        {
            "message_id": "ccde552d-43da-4f03-89bd-88860a7940ac:2",
            "to": "[email protected]",
            "cc": "[email protected]",
            "bcc": "[email protected]",
            "from": "[email protected]",
            "subject": "Bulk email from Email API"
        }
    ],
    "error": []
}