Send Email over API
You can use API as another way of sending emails to your customers.
Fully-Featured Email
To send a fully-featured email - send one or more email messages with attachments to one or more destination addresses - see Send a Fully Featured Email on the Infobip API developer hub.
Parameter name |
Type |
Description |
---|---|---|
from |
string |
Email address with optional sender name. Example: "Jane Doe <jane.doe@somecompany.com>". |
to |
string |
Email address of the recipients with optional placeholder values for personalized content. |
replyTo |
string |
Email address to which recipients of the email can reply. |
subject |
string |
Message subject. |
text |
string |
Body of the message. |
html |
string |
HTML body of the message. If |
templateId |
int |
Template identifier based on which email message is generated. Create the template in the web interface. If the |
defaultPlaceholders |
string |
Default placeholder values used for all recipients. The values are used to generate the email message. |
attachment |
file |
File attachment. |
bulkId |
string |
The identifier uniquely identifies the sent email request. This filter enables you to query delivery reports for all the messages using just one request. You will receive a |
messageId |
string |
The identifier that uniquely identifies the message sent for a recipient. |
sendAt |
datetime |
Date and time when the message is to be sent. Used for scheduled email (Email is not sent immediately, but at scheduled time). |
intermediateReport |
boolean |
The real-time, intermediate delivery report that is sent on your callback server. Can be |
notifyUrl |
string |
The URL on your callback server on which the Delivery report will be sent. |
notifyContentType |
string |
Preferred Delivery report content type. Can be |
callbackData |
string |
Additional client's data that will be sent on the |
track |
boolean |
Enable or disable open and click tracking. Can be |
trackOpens |
boolean |
This parameter enables or disables track open feature. Can be |
trackClicks |
boolean |
This parameter enables or disables track click feature. Can be |
trackingUrl |
string |
The URL on your callback server on which the open and click notifications are sent. If you are passing this parameter then |
inlineImage | string | Using an inline image, it is possible to insert the image file inside the HTML code of the email by using cid:FILENAME instead of providing any external link to image. |
Request example
curl -s --user user:password \
https://e6jqr.api.infobip.com/email/1/send \
-F from='Jane Smith ' \
-F to='john.smith@somedomain.com' \
-F replyTo='all.replies@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text' \
--form-string html='Html bodyRich HTML message body.' \
-F attachment=@files/image1.jpg \
-F bulkId='customBulkId' \
-F intermediateReport='true' \
-F notifyUrl='https://www.example.com/email/advanced' \
-F notifyContentType = 'application/json' \
-F callbackData = 'DLR callback data'
Send Email to Multiple Recipients
Send the same email to multiple recipient addresses by including more than one to
parameters in the request.
Send an Email With Multiple Attachments
To send an email with more than one attachment, add multiple attachment parameters in the request.
Send Email to Multiple To, Cc, Bcc Recipients
Send the same email to multiple recipient addresses by including more than one to, cc, bcc parameters in the request.
curl -s --user user:password \
https://e6jqr.api.infobip.com/email/2/send \
-F from='Jane Smith ' \
-F to='john.smith@somedomain.com' \
-F to='jane.smith@somedomain.com' \
-F cc='juliet.smith@somedomain.com' \
-F cc='abram.smith@somedomain.com' \
-F bcc='joy.smith@somedomain.com' \
-F bcc='clare.smith@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text' \
--form-string html='Html bodyRich HTML message body.' \
-F attachment=@files/image1.jpg
DISCLAIMER
- If all recipients in the to field are rejected, then the entire request will be rejected.
- Placeholders are not allowed when cc/bcc is provided.
- Tracking of clicks and opens events are not supported when cc/bcc is provided.
- Duplicate email addresses across to/cc/bcc is not supported and will result in undefined behavior. Validation/filters will be added later to remove duplicates.
- Resource https://e6jqr.api.infobip.com/email/1/send does not support cc/bcc feature.
Send Personalized Emails Using Templates
Send personalized emails by adding placeholder values within the to
parameter of the request. If you want to send the message based on a previously defined template, pass the template identifier value in the templateId parameter. To manage Templates login to the Infobip web interface
Send an Email With Custom MessageID
Send emails with custom messageId
by including your unique messageId
within the to
parameter of the request.
Send Emails with Dynamic Content
To send email with dynamic content, use the Template language within your HTML content and define the placeholder values in the to
parameter of the request. Add any of the available Template language constructs in the HTML content to solve substitutions, conditional statements, or iterations.
To use the new Template language constructs in an API request, provide the parameter templateLanguageVersion=2.
If you prefer to use the old handlebar {{helpers}} in your HTML, do not specify the TemplateLanguageVersion parameter in the API request. The following table shows examples for the handlebar {{helpers}}.
See Send Fully Featured Email in the API Developer Hub for more information.
Handlebar helper examples
HTML REQUEST |
TO JSON REQUEST |
RESOLVED HTML |
---|---|---|
Helper Example: #eq |
||
{{#eq name "Bob"}} Dear {{name}} {{else}} Hi {{name}} {{/eq}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" } } |
Dear Bob |
Helper Example: #each |
||
{{#each friends}} Hi {{this}} {{/each}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "friends":["Bob","John","Jack"] } } |
Hi Bob Hi John Hi Jack |
Helper Example: #unlessEq |
||
{{#unlessEq name "Bob"}} Dear {{name}} {{else}} Hi {{name}} {{/unlessEq}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" } } |
Hi Bob |
Helper Example: #default |
||
Hi {{name}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" } } |
Hi Bob |
Helper Example: #gt |
||
{{#gt age 12}} Welcome {{name}}! {{else}} Hey {{name}}, you are under age {{/gt}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } } |
Hey Bob, you are under age |
Helper Example: #lt |
||
{{#lt age 12}} Welcome {{name}}! {{else}} Sorry {{name}}, This is kids arena {{/lt}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } } |
Welcome Bob! |
Helper Example: #equalsIgnoreCase |
||
{{#equalsIgnoreCase gender "male"}} Dear Mr {{name}} {{else}} Dear customer {{/equalsIgnoreCase}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "gender": "MALE" } }
|
Dear Mr Bob |
Helper Example: #gte |
||
{{#gte age 12}} Welcome {{name}}! {{else}} Hey {{name}}, you are under age {{/gte}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Hey Bob, you are under age |
Helper Example: #lte |
||
{{#lte age 12}} Welcome {{name}}! {{else}} Sorry {{name}}, This is kids arena {{/lte}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } } |
Welcome Bob! |
Helper Example: #compare |
||
{{#compare name "!=" "Bob"}} Hi {{name}} {{else}} Dear Bob {{/compare}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Jane" , "age":10 } } |
Hi Jane |
Helper Example: #equals |
||
{{#equals name "Bob"}} Dear {{name}} {{else}} Hi {{name}} {{/equals}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" } }
|
Dear Bob |
Helper Example: #lessThan |
||
{{#lessThan age 12}} Welcome {{name}}! {{else}} Sorry {{name}}, This is kids arena {{/lessThan}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Welcome Bob! |
Helper Example: #lessThanOrEquals |
||
{{#lessThanOrEquals age 12}} Welcome {{name}}! {{else}} Sorry {{name}}, This is kids arena {{/lte}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } } |
Welcome Bob! |
Helper Example: #greaterThan |
||
{{#greaterThan age 12}} Welcome {{name}}! {{else}} Hey {{name}}, you are under age {{/greaterThan }} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Hey Bob, you are under age |
Helper Example: #greaterThanOrEquals |
||
{{#greaterThanOrEquals age 12}} Welcome {{name}}! {{else}} Hey {{name}}, you are under age {{/greaterThanOrEquals }} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Hey Bob, you are under age |
Helper Example: #when |
||
{{#when name "!=" "Bob"}} Hi {{name}} {{else}} Dear Bob {{/when}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Jane" , "age":10 } }
|
Hey Jane |
Helper Example: #contains |
||
{{#contains friends "Bob"}} Hi {{this}} {{/each}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "friends":["Bob","John","Jack"] } } |
Hi Bob |
Helper Example: #and |
||
{{#and great magnificent}} Bob{{else}}Jane {{/and}}
|
{ "to": "john.smith@somedomain.com", "placeholders": { "great": true, "magnificent": true } }
|
Hi Bob |
Helper Example: #formatNumber |
||
{{#formatNumber price}} {{/formatNumber}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "price":10000 } } |
10,000 |
Helper Example: #isTruthy |
||
{{#isTruthy Male}} Hi Bob {{else}} Hi Jane {{/isTruthy}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "Male": true } }
|
Hi Bob |
Helper Example: #isFalsey |
||
{{#isFalsey Male}} Hi Bob {{else}} Hi Jane {{/isFalsey}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "Male": true } }
|
Hi Jane |
Helper Example: #ifEven |
||
{{#ifEven age}} Hi Bob {{else}} Hi Jane {{/ifEven}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "age": 20 } }
|
Hi Bob |
Helper Example: #ifOdd |
||
{{#ifOdd age}} Hi Bob {{else}} Hi Jane {{/ifOdd}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "age": 20 } }
|
Hi Jane |
Helper Example: #ifNth |
||
{{#ifNth age balance}} Hi Bob {{else}} Hi Jane {{/ifNth}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "age": 20, "balance": 20000 } }
|
Hi Bob |
Helper Example: #is |
||
{{#is name "Bob"}} Dear {{name}} {{else}} Hi {{name}} {{/is}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Dear Bob |
Helper Example: #isnt |
||
{{#isnt name "Bob"}} Dear {{name}} {{else}} Hi {{name}} {{/isnt}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "age":10 } }
|
Hi Bob |
Helper Example: #neither |
||
{{#neither great magnificent}} A{{else}}B {{/neither}} |
{ "to": "john.smith@somedomain.com", "placeholders": { great: true, magnificent: false } } |
B |
Helper Example: #not |
||
{{#not great}} A {{else}} B {{/not}} |
{ "to": "john.smith@somedomain.com", "placeholders": { great: true, magnificent: false } }
|
B |
Helper Example: #or |
||
{{#or great magnificent}} A {{else}} B {{/or}} |
{ "to": "john.smith@somedomain.com", "placeholders": { great: true, magnificent: false } }
|
A |
Helper Example: #unlessGt |
||
{{#unlessGt physics chemistry}} Hi {{name}} your score in Physics :{{physics}} {{else}} Hi {{name}} your score in Chemistry : {{chemistry}} {{/unlessGt}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "physics": 70 , "chemistry": 75 } }
|
Hi Bob your score in Physics : 70 |
Helper Example: #unlessLt |
||
{{#unlessLt physics chemistry}} Hi {{name}} your score in Physics : {{physics}} {{else}} Hi {{name}} your score in Chemistry : {{chemistry}} {{/unlessLt}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "physics": 70 , "chemistry": 75 } }
|
Hi Bob your score in Chemistry : 75 |
Helper Example: #unlessGteq |
||
{{#unlessGteq physics chemistry}} Hi {{name}} your score in Physics : {{physics}} {{else}} Hi {{name}} your score in Chemistry : {{chemistry}} {{/unlessGteq}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "physics": 70 , "chemistry": 75 } }
|
Hi Bob your score in Physics : 70 |
Helper Example: #unlessLteq |
||
{{#unlessLteq physics chemistry}} Hi {{name}} your score in Physics : {{physics}} {{else}} Hi {{name}} your score in Chemistry : {{chemistry}} {{/unlessLteq}} |
{ "to": "john.smith@somedomain.com", "placeholders": { "name": "Bob" , "physics": 70 , "chemistry": 75 } }
|
Hi Bob your score in Chemistry : 75 |
Email Delivery Reports
This method allows you to get one-time delivery reports for sent emails.
NOTE
Delivery report will be returned only once. Additional delivery report request will return an empty collection.
Parameters
Property name |
Type |
Description |
---|---|---|
bulkId |
string |
The ID uniquely identifies a group of Email requests. This filter will enable you to query delivery reports for all the messages with the same bulk id using just one request. |
messageId |
string |
Message ID for which report is requested. |
limit |
int |
Maximum number of reports. |
GET /email/1/reports
|
|
|
Get Reports by Message ID
GET /email/1/reports?messageId=
Get the Initial Two Delivery Reports
GET /email/1/reports?limit=2 HTTP/1.1
Get Reports by Bulk ID
GET /email/1/reports?bulkId=lrzkq6gatdkxouhrkgni HTTP/1.1
Email Messages Logs
This method allows you to get logs for email messages. None of the query parameters is mandatory for this request. Any combination of parameters can be used to filter results. Some examples are shown below.
LOGS AVAILABILITY
Email logs are available for the last 48 hours!
Response format
If successful, the response header HTTP status code will be 200 OK
and the message logs will be returned.
If you try to send a message without authorization, you will get a response with HTTP status code 401 Unauthorized
.
If you use this method too many times in a short period of time, you will get the 429 Too Many Requests
status code. This prevents misusing logs in cases where reports would be more appropriate.
Get Logs With Multiple Messageid Filters
From, to and limit accept a single parameter which will be used to filter response message logs.
Get Logs With Date Range and General Status Filters
SentSince and generalStatus accept a single parameter which will be used to filter response message logs.
Get Logs Bulk ID
To use this method to get logs for your email messages, check out the Email Message Logs article on the Infobip API Developer Hub.
Tracking Notifications
If trackingUrl
is passed, you will be notified whenever the email is opened or an URL in the email is clicked by the recipient. The structure of the data passed in the open and click notifications is shown below.
Open Notifications
{
"notificationType": "OPENED",
"domain": "sendingdomain.com",
"recipient": "john.smith@somecompany.com",
"sendDateTime": 1517652288663,
"messageId": "zl3cf7frmy48ueavnnxy",
"callbackData": "Email open and click callback data",
"bulkId": "8pok2duu132mojj587zc",
"recipientInfo": {
"deviceType": "Desktop",
"os": "Windows XP",
"deviceName": "PC"
}
}
Click Notifications
{
"notificationType": "CLICKED",
"domain": "sendingdomain.com",
"recipient": "jane.smith@somecompany.com",
"url": "http://www.example.com/landingpage.html",
"sendDateTime": 1517652288646,
"messageId": "zsf6q5vjgn1y6qqn65g7",
"callbackData": "Email open and click callback data",
"bulkId": "8pok2duu132mojj587zc",
"recipientInfo": {
"deviceType": "Desktop",
"os": "Windows XP",
"deviceName": "PC"
}
}