Documentation and APIs

Learn how to use our serverless platform to create voice, video and messaging applications and services by reading our getting started guide. It's the best way to become familiar with the platform architecture and capabilities.

Number Management

SMS

Anonymize

Authenticate – OTP

Authenticate – One Tap Authentication

Engage

Programmable Voice(India)

Programmable Voice (USA)

Email

Explore our extensive Email API documentation and learn how to execute targeted email blasts, trigger personalized journeys based on user behavior, and other wide range of operations. You can integrate our REST APIs to automate tasks, integrate with other systems, and build custom solutions that drive productivity.

Contact

Create a folder

POST: /v3/contacts/folder

Body Params:

Param	Type	Description	Example
Name	String	Name of the folder	Test_folder

Responses:

Method	Description	Response body
200	successfully created ID of the folder created	`{ "id": 5 }`
400	Bad request

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts/folders \ 
    -H 'api-key: {{api-key}}I' \ 
    -d '{
        "name": "{{folder-name}}"
    }'

Example:

copy

curl -X POST \. 
    {{baseUrl}}/v3/contacts/folders \  
    -H 'api-key: {{api-key}}I' \ 
    -d '{
        "name": "test_folder"
    }'

Create a list

POST: /v3/contacts/lists

Body Params:

Param	Type	Description	Example
Name	String	Name of the list	Test_list
folderId	Integer	Id of the parent folder in which this list is to be created	5

Responses:

Method	Description	Response body
200	successfully created ID of the list created	`{ "id": 16 }`
400	Bad request

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts/lists \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "name": "{{list name}}",
        "folderId": {{folder id}}
    }'

Example:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts/lists \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "name": "test_list",
        "folderId": 5
    }'

Create a contact

POST: /v3/contacts

Body Params:

Param	Type	Description	Example
Email	String	Email address of the user. Mandatory	elly@example.com
ext_id	String	Pass your own Id to create a contact.
attributes	Object	Pass the set of attributes and their values. The attribute’s parameter should be passed in capital letter while creating a contact. These attributes must be present in your account.	`{ "FNAME": "Elly", "LNAME": "Roger" }`
emailBlacklisted	Boolean	Set this field to blacklist the contact for emails	True
smsBlacklisted	Boolean	Set this field to blacklist the contact for SMS	true
listIds	Array of integers	Ids of the lists to add the contact to	[36, 68]
updateEnabled	Boolean	Facilitate to update the existing contact in the same request	true
smtpBlacklistSender	Array of Strings	transactional email forbidden sender for contact. Use only for email Contact. ( only available if updateEnabled = true )	[“user@example.com”]

Responses:

Method	Description	Response body
201	Description	`{ "id": 21 }`
204	Contact updated
400	Bad request

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "email": "{{receiver-email}]",
        "ext_id": "{{externalId}}",
        "attributes": {
            "FNAME": "{{receiver-firstname}}",
            "LNAME": "{{receiver-lastname}}"
        },
        "emailBlacklisted": false,
        "smsBlacklisted": false,
        "listIds": [{{listId}}],
        "updateEnabled": false,
        "smtpBlacklistSender": [
            "{{blacklisted-email}}"
        ]
    }'

Example:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "email": "elly@example.com",
        "ext_id": "externalId",
        "attributes": {
            "FNAME": "Elly",
            "LNAME": "Roger"
        },
        "emailBlacklisted": false,
        "smsBlacklisted": false,
        "listIds": [
            36
        ],
        "updateEnabled": false,
        "smtpBlacklistSender": [
            "user@example.com"
        ]
    }'

Import contact

It returns the background process ID which on completion calls the notify URL that you have set in the input.

POST: /v3/contacts

Body Params:

Param	Type	Description	Example
fileUrl	url	Mandatory if fileBody and jsonBody is not defined. URL of the file to be imported (no local file). Possible file formats: .txt, .csv, .json	https://importfile.domain.com
fileBody	String	Mandatory if fileUrl and jsonBody is not defined. CSV content to be imported. Use semicolon to separate multiple attributes. Maximum allowed file body size is 10MB . However we recommend a safe limit of around 8 MB to avoid the issues caused due to increase of file body size while parsing. Please use fileUrl instead to import bigger files.	NAME; SURNAME; EMAIL Smith; John; john.smith@example.com Roger; Ellie; ellie36@example.com
jsonBody	array of objects	Mandatory if fileUrl and fileBody is not defined. JSON content to be imported. Maximum allowed json body size is 10MB . However we recommend a safe limit of around 8 MB to avoid the issues caused due to increase of json body size while parsing. Please use fileUrl instead to import bigger files.	`[ { "email": "ndicky0@ocn.ne.jp", "attributes": { "LNAME": "Noemi", "FNAME": "Dicky", "COUNTRY": "DE", "BIRTHDAY": "11/02/1989", "PREFERED_COLOR": "BLACK" } } ]`
listIds	Array of integers	Mandatory if newList is not defined. Ids of the lists in which the contacts shall be imported.	[2, 4, 7]
notifyUrl	url	URL that will be called once the import process is finished	http://requestb.in/173lyyx1
listIds	Array of integers	Ids of the lists to add the contact to	[36, 68]
newList	object	To create a new list and import the contacts into it, pass the listName and an optional folderId.	`{ "listName": "ContactImport - 2017-05", "folderId": 2 }`
emailBlacklist	Boolean	To blacklist all the contacts for email
disableNotification	Boolean	To disable email notification
smsBlacklist	Boolean	To blacklist all the contacts for sms
updateExistingContacts	Boolean	To facilitate the choice to update the existing contacts
emptyContactsAttributes	Boolean	To facilitate the choice to erase any attribute of the existing contacts with empty value. emptyContactsAttributes = true means the empty fields in your import will erase any attribute that currently exists, & emptyContactsAttributes = false means the empty fields will not affect your existing data ( only available if updateExistingContacts set to true )

Responses:

Method	Description	Response body
200	process id created	`{ "processId": 78 }`
400	Bad request	`{ "code": "method_not_allowed", "message": "POST Method is not allowed on this path" }`

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts/import \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "fileUrl": "https://importfile.domain.com",
        "fileBody": "NAME;SURNAME;EMAIL ",
        "jsonBody": [
            {
                "email": "{{receiver-email}]",
                "attributes": {
                    "FNAME": "{{receiver-firstname}}",
                    "LNAME": "{{receiver-lastname}}"
                }
            }
        ],
        "listIds": [
            {{list_id}}
        ],
        "notifyUrl": {{notify_url}},
        "newList": {
            "listName": {{list_name}},
            "folderId": {{folder_id}}
        },
        "emailBlacklist": false,
        "disableNotification": false,
        "smsBlacklist": false,
        "updateExistingContacts": true,
        "emptyContactsAttributes": true
    }'

Example:

copy

curl -X POST \ 
    {{baseUrl}}/v3/contacts/import \ 
    -H 'api-key: {{api-key}}' \ 
    -d '{
        "fileUrl": "https://importfile.domain.com",
        "fileBody": "NAME;SURNAME;EMAIL\nSmith;John;john.smith@example.com\nRoger;Ellie;ellie36@example.com",
        "jsonBody": [
            {
                "email": "ndicky0@ocn.ne.jp",
                "attributes": {
                    "LNAME": "Noemi",
                    "FNAME": "Dicky",
                    "COUNTRY": "DE",
                    "BIRTHDAY": "11/02/1989",
                    "PREFERED_COLOR": "BLACK"
                }
            }
        ],
        "listIds": [
            76
        ],
        "notifyUrl": "http://requestb.in/173lyyx1",
        "newList": {
            "listName": "ContactImport - 2017-05",
            "folderId": 2
        },
        "emailBlacklist": false,
        "disableNotification": false,
        "smsBlacklist": false,
        "updateExistingContacts": true,
        "emptyContactsAttributes": true
    }'

Get list in folder

GET: /v3/contacts/folders/{folderId}/lists

Path Params:

Param	Type	Description	Example
folderId	Integer	Id of the parent folder in which this list exists.	16

Query Params:

Param	Type	Description	Example
Limit	Integer	Number of documents per page	10
Offset	Integer	Index of the first document of the page	0
Sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc

Responses:

Method	Description	Response body
200	Folder’s Lists details	`{ "lists": [ { "id": 46, "name": "Reactiv", "totalSubscribers": 7655, "totalBlacklisted": 0, "uniqueSubscribers": 7655 } ], "count": 1 }`
400	Bad request
404	Folder ID not found

CURL:

copy

curl -X GET \ '{{baseUrl}}/v3/contacts/folders/{{folder_id}}/lists' \ 
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/contacts/folders/16/lists' \ 
    -H 'api-key: {{api-key}}' \

Get list info

GET: /v3/contacts/lists/{listId}

Path Params:

Param	Type	Description	Example
listId	Integer	Id of the list	16

Responses:

Method Description Response body

200

Folder’s Lists details

Method	Description	Response body
200	Folder’s Lists details	`{ "id": 16, "name": "Newsletter_Weekly", "totalSubscribers": 6533, "totalBlacklisted": 63, "uniqueSubscribers": 6596, "folderId": 1, "createdAt": "2016-02-26T11:56:08Z", "campaignStats": [ { "campaignId": 15, "stats": { "uniqueClicks": 701, "clickers": 789, "complaints": 0, "delivered": 6632, "sent": 6645, "softBounces": 34, "hardBounces": 4, "uniqueViews": 3442, "unsubscriptions": 4, "viewed": 4322, "deferred": 0 } } ], "dynamicList": false }`
400	Bad request
404	List ID not found


{
    "id": 16,
    "name": "Newsletter_Weekly",
    "totalSubscribers": 6533,
    "totalBlacklisted": 63,
    "uniqueSubscribers": 6596,
    "folderId": 1,
    "createdAt": "2016-02-26T11:56:08Z",
    "campaignStats": [
        {
            "campaignId": 15,
            "stats": {
                "uniqueClicks": 701,
                "clickers": 789,
                "complaints": 0,
                "delivered": 6632,
                "sent": 6645,
                "softBounces": 34,
                "hardBounces": 4,
                "uniqueViews": 3442,
                "unsubscriptions": 4,
                "viewed": 4322,
                "deferred": 0
            }
        }
    ],
    "dynamicList": false
}

400 Bad request

404 List ID not found

CURL:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/contacts/lists/{{list_id}}' \ 
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/contacts/lists/16' \ 
    -H 'api-key: {{api-key}}' \

Get all contacts

GET: /v3/contacts/

Query Params:

Param	Type	Description	Example
Limit	Integer	Number of documents per page	10
Offset	Integer	Index of the first document of the page	0
modifiedSince	String	Filter (urlencoded) the contacts modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result.
createdSince	String	Filter (urlencoded) the contacts created after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result.
Sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc

Responses:

Method Description Response body

200

All contacts listed

Method	Description	Response body
200	All contacts listed	`{ "contacts": [ { "email": "contact1@example.com", "id": 247, "emailBlacklisted": true, "smsBlacklisted": true, "createdAt": "2017-05-01T17:05:03Z", "modifiedAt": "2017-05-01T17:05:03Z", "listIds": [ 43, 58 ] } ], "count": 1 }`
400	Bad request


{
    "contacts": [
        {
            "email": "contact1@example.com",
            "id": 247,
            "emailBlacklisted": true,
            "smsBlacklisted": true,
            "createdAt": "2017-05-01T17:05:03Z",
            "modifiedAt": "2017-05-01T17:05:03Z",
            "listIds": [
                43,
                58
            ]
        }
    ],
    "count": 1
}

400 Bad request

CURL:

copy

curl -X GET \ 
    {{baseUrl}}/v3/contacts \ 
    -H 'api-key: {{api-key}}' \

Get contacts in list

GET: /v3/contacts/folders/{folderId}/lists

Path Params:

Param	Type	Description	Example
listId	Integer	Id of the list	16

Query Params:

Param	Type	Description	Example
modifiedSince	String	Filter (urlencoded) the contacts modified after a given UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result.
Limit	Integer	Number of documents per page	10
Offset	Integer	Index of the first document of the page	0
Sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc

Responses:

Method Description Response body

200

Contact informations

Method	Description	Response body
200	Contact informations	`{ "contacts": [ { "email": "alex.pain@example.com", "id": 45, "emailBlacklisted": false, "smsBlacklisted": true, "createdAt": "2017-05-12T12:30:00Z", "modifiedAt": "2017-05-12T12:30:00Z", "listIds": [ 12, 9, 20 ], "listUnsubscribed": [ 1, 2 ], "attributes": { "LASTNAME": "Pain", "FIRSTNAME": "Alex", "DOB": "2010-12-31", "GENDER": "Kid" } } ], "count": 17655 }`
400	Bad request
404	List ID not found


{
    "contacts": [
        {
            "email": "alex.pain@example.com",
            "id": 45,
            "emailBlacklisted": false,
            "smsBlacklisted": true,
            "createdAt": "2017-05-12T12:30:00Z",
            "modifiedAt": "2017-05-12T12:30:00Z",
            "listIds": [
                12,
                9,
                20
            ],
            "listUnsubscribed": [
                1,
                2
            ],
            "attributes": {
                "LASTNAME": "Pain",
                "FIRSTNAME": "Alex",
                "DOB": "2010-12-31",
                "GENDER": "Kid"
            }
        }
    ],
    "count": 17655
}

400 Bad request

404 List ID not found

CURL:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/contacts/lists/{{List_id}}/contacts' \ 
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/contacts/lists/18/contacts' \ 
    -H 'api-key: {{api-key}}' \

Template

Create an email template

POST: /v3/smtp/templates

Body Params:

Param	Type	Description	Example
Tag	string	Tag of the template
Sender	Object	Sender details including id or email and name (optional). Only one of either Sender’s email or Sender’s ID shall be passed in one request at a time	`{ "name": "xyz", "email": "example@abc.com" } { "name": "xyz", "id": 123 }`
templateName	String	Name of the template
htmlContent	String	Body of the message (HTML version). The field must have more than 10 characters. REQUIRED if htmlUrl is empty
htmlUrl	url	Url which contents the body of the email message. REQUIRED if htmlContent is empty
Subject	String	Subject of the template
replyTo	Boolean	Email on which campaign recipients will be able to reply to
toField	string	To personalize the To Field. If you want to include the first name and last name of your recipient, add {FNAME} {LNAME}. These contact attributes must already exist in your Brevo account. If input parameter params used please use {{contact.FNAME}} {{contact.LNAME}} for personalization
attachmentUrl	url	Absolute url of the attachment (no local file). Extension allowed: xlsx, xls, ods, docx, docm, doc, csv, pdf, txt, gif, jpg, jpeg, png, tif, tiff, rtf, bmp, cgm, css, shtml, html, htm, zip, xml, ppt, pptx, tar, ez, ics, mobi, msg, pub and eps’
isActive	Boolean	Status of template. isActive = true means template is active and isActive = false means template is inactive

Responses:

Method	Description	Response body
200	Template successfully created	`{ "id": 5 }`
400	Bad request

CURL:

copy

curl -X POST \
    {{baseUrl}}/v3/smtp/templates \
    -H 'Content-Type: application/json' \
    -H 'api-key: {{api-key}}' \
    -d '{
        "tag": "{{Tag Name}}",
        "sender": {
            "name": {{sender_name}},
            "email": {{sender_email}}
        },
        "templateName": "{{Template Name}}",
        "htmlContent": "{{Email content}}",
        "subject": "{{Email Subject}}",
        "replyTo": "{{replyTo_email}}",
        "toField": "{}",
        "isActive": true
    }'

Example:

copy

curl -X POST \
    {{baseUrl}}/v3/smtp/templates \
    -H 'Content-Type: application/json' \
    -H 'api-key: {{api-key}}' \
    -d '{
        "tag": "OrderConfirmation",
        "sender": {
            "name": "Mary from MyShop",
            "email": "contact@myshop.com",
            "id": 3
        },
        "templateName": "Order Confirmation - EN",
        "htmlContent": "The order n°xxxxx has been confirmed. Thanks for your purchase",
        "htmlUrl": "https://html.domain.com",
        "subject": "Thanks for your purchase !",
        "replyTo": "support@myshop.com",
        "toField": "{FNAME} {LNAME}",
        "attachmentUrl": "https://attachment.domain.com",
        "isActive": true
    }'

Get the list of email templates

GET: /v3/smtp/templates

Query Params:

Param	Type	Description	Example
templateStatus	Boolean	Filter on the status of the template. Active = true, inactive = false
Limit	Integer	Number of documents per page	50
Offset	Integer	Index of the first document of the page	0
Sort	String	Sort the results in the ascending or descending order of record creation. Default order is descending.	Desc, asc

Responses:

Method Description Response body

200

transactional email templates informations.

Method	Description	Response body
200	transactional email templates informations.	`{ "count": 1, "templates": [ { "id": 5, "name": "ChristomasTimeTemplate", "subject": "Merry Christmas", "isActive": false, "testSent": false, "sender": { "name": "John", "email": "john.smith@example.com", "id": 23 }, "replyTo": "replyto@domain.com", "toField": "", "tag": "Festival", "htmlContent": "HTML CONTENT 1", "createdAt": "2016-02-24T14:44:24Z", "modifiedAt": "2016-02-24T15:37:11Z" } ] }`
400	Bad request


{
    "count": 1,
    "templates": [
        {
            "id": 5,
            "name": "ChristomasTimeTemplate",
            "subject": "Merry Christmas",
            "isActive": false,
            "testSent": false,
            "sender": {
                "name": "John",
                "email": "john.smith@example.com",
                "id": 23
            },
            "replyTo": "replyto@domain.com",
            "toField": "",
            "tag": "Festival",
            "htmlContent": "HTML CONTENT 1",
            "createdAt": "2016-02-24T14:44:24Z",
            "modifiedAt": "2016-02-24T15:37:11Z"
        }
    ]
}

400 Bad request

CURL:

copy

curl -X GET \ 
    {{baseUrl}}/v3/smtp/templates \ 
    -H 'api-key: {{api-key}}' \

Get Template Info

GET: /v3/smtp/templates/{templateId}

Path Params:

Param	Type	Description	Example
templateId	Integer	id of the template	33

Responses:

Method Description Response body

200

Email template information.

Method	Description	Response body
200	Email template information.	`{ "id": 33, "name": "OrderConfirmation", "subject": "Order Confirmation : Thanks for your Purchase !", "isActive": true, "testSent": false, "sender": { "name": "John", "email": "john.smith@example.com", "id": 26 }, "replyTo": "replyto@domain.com", "toField": "", "tag": "", "htmlContent": "HTML CONTENT 4", "createdAt": "2016-02-25T11:53:26Z", "modifiedAt": "2016-02-25T11:53:26Z", "doiTemplate": false }`
400	Bad request
404	Template ID not found


{
    "id": 33,
    "name": "OrderConfirmation",
    "subject": "Order Confirmation : Thanks for your Purchase !",
    "isActive": true,
    "testSent": false,
    "sender": {
        "name": "John",
        "email": "john.smith@example.com",
        "id": 26
    },
    "replyTo": "replyto@domain.com",
    "toField": "",
    "tag": "",
    "htmlContent": "HTML CONTENT 4",
    "createdAt": "2016-02-25T11:53:26Z",
    "modifiedAt": "2016-02-25T11:53:26Z",
    "doiTemplate": false
}

400 Bad request

404 Template ID not found

CURL:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/templates/{{Template_Id}}' \ 
     -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/templates/48' \ 
     -H 'api-key: {{api-key}}' \

Email

Send A Plain Text Email

POST: /v3/smtp/email

Body Params:

Param	Type	Description	Example
Sender	Object	Mandatory if templateId is not passed. Pass name (optional) and email or id of sender from which emails will be sent. name will be ignored if passed along with sender id.	`{ "name": "Mary from MyShop", "email": "no-reply@myshop.com" }`
To	Array of Objects	Mandatory if messageVersions are not passed, ignored if messageVersions are passed List of email addresses and names (optional) of the recipients	`[ { "name": "Jimmy", "email": "jimmy98@example.com" }, { "name": "Joe", "email": "joe@example.com" } ]`
Bcc	Array of Objects	List of email addresses and names (optional) of the recipients in bcc
Cc	Array of Objects	List of email addresses and names (optional) of the recipients in bcc
htmlContent	String	HTML body of the message. Mandatory if ‘templateId’ is not passed, ignored if ‘templateId’ is passed
textContent	String	Plain Text body of the message. Ignored if ‘templateId’ is passed
subject	String	Subject of the message. Mandatory if ‘templateId’ is not passed
replyTo	Object	Email (required), along with name (optional), on which transactional mail recipients will be able to reply back.	`{ "email": "ann6533@example.com", "name": "Ann" }`
attachment	Array of Objects	Pass the absolute URL (no local file) or the base64 content of the attachment along with the attachment name. Mandatory if attachment content is passed.	`[ { "url": "https://attachment.domain.com/myAttachmentFromUrl.jpg", "name": "myAttachmentFromUrl.jpg" }, { "content": "base64 example content", "name": "myAttachmentFromBase64.jpg" } ]`
Headers	object	Pass the set of custom headers (not the standard headers) that shall be sent along the mail headers in the original email. ‘sender.ip’ header can be set (only for dedicated ip users) to mention the IP to be used for sending transactional emails. Headers are allowed in This-Case-Only (i.e. words separated by hyphen with first letter of each word in capital letter), they will be converted to such case styling if not in this format in the request payload.	`{ "sender.ip": "1.2.3.4", "X-Mailin-custom": "some_custom_header", "idempotencyKey": "abc-123" }`
templateId	Integer	Id of the template.
params	Object	Pass the set of attributes to customize the template.	`{ "FNAME": "Joe", "LNAME": "Doe" }`
tags	Array of Strings	Tag your emails to find them more easily
batchId	String	Valid UUIDv4 batch id to identify the scheduled batches transactional email. If not passed we will create a valid UUIDv4 batch id at our end.

Responses:

Method	Description	Response body
201	transactional email sent	`{ "messageId": "<201798300811.5787683@relay.domain.com>" }`
202	transactional email scheduled
400	Bad request

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/smtp/email \ 
    -H 'Content-Type: application/json' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "sender": {
            "name": "digo",
            "email": "digo@sib.digo.link"
        },
        "to": [
            {
                "email": "{{Reciever Email}}",
                "name": "{{Reciver Name}}"
            }
        ],
        "subject": "{{Email Subject}}",
        "htmlContent": "{{Email content}}"
    }'

Example: send transactional mail to single receiver:

copy

curl -X POST \ 
    {{baseUrl}}/v3/smtp/email \ 
    -H 'Content-Type: application/json' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "sender": {
            "name": "Mary from MyShop",
            "email": "no-reply@myshop.com",
            "id": 2
        },
        "to": [
            {
                "email": "jimmy98@example.com",
                "name": "Jimmy"
            }
        ],
        "bcc": [
            {
                "email": "helen9766@example.com",
                "name": "Helen"
            }
        ],
        "cc": [
            {
                "email": "ann6533@example.com",
                "name": "Ann"
            }
        ],
        "htmlContent": "<!DOCTYPE html> <html> <body> <h1>Confirm you email</h1> <p>Please confirm your email address by clicking on the link below</p> </body> </html>",
        "textContent": "Please confirm your email address by clicking on the link https://text.domain.com",
        "subject": "Login Email confirmation",
        "replyTo": {
            "email": "ann6533@example.com",
            "name": "Ann"
        },
        "attachment": [
            {
                "url": "https://attachment.domain.com/myAttachmentFromUrl.jpg",
                "content": "b3JkZXIucGRm",
                "name": "myAttachment.png"
            }
        ],
        "templateId": 2,
        "params": {
            "FNAME": "Joe",
            "LNAME": "Doe"
        },
        "tags": [
            "tag1"
        ],
        "batchId": "5c6cfa04-eed9-42c2-8b5c-6d470d978e9d"
    }'

Example: Example: send transactional mail to multiple receivers.

copy

curl -X POST \ 
    {{baseUrl}}/v3/smtp/email \ 
    -H 'Content-Type: application/json' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "sender": {
            "name": "digo",
            "email": "digo@sib.digo.link"
        },
        "to": [
            {
                "email": "jimmy98@example.com",
                "name": "Jimmy"
            },
            {
                "email": "test@test.com",
                "name": "Test"
            }
        ],
        "subject": "Test mail",
        "htmlContent": "Hi, this is test mail"
    }'

Example: send transactional mail with templateId

copy

curl -X POST \
    {{baseUrl}}/v3/smtp/email \   
    -H 'Content-Type: application/json' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "templateId": 48,
        "to": [
            {
                "email": "meghna.patil@tatacommunications.com",
                "name": "Meghna"
            },
            {
                "email": "test@test.com",
                "name": "Test"
            }
        ]
    }'

Campaign

Create an email campaign

POST: /v3/smtp/email

Body Params:

Param	Type	Description	Example
tag	String	Tag of the campaign
sender	Object	Sender details including id or email and name (optional). Only one of either Sender’s email or Sender’s ID shall be passed in one request at a time	`{ "name": "xyz", "email": "example@abc.com" } { "name": "xyz", "id": 123 }`
name	String	Name of the campaign
htmlContent	String	Mandatory if htmlUrl and templateId are empty. Body of the message (HTML).
htmlUrl	url	Mandatory if htmlContent and templateId are empty. Url to the message (HTML). For example:	https://html.domain.com
templateId	Integer	Mandatory if htmlContent and htmlUrl are empty. Id of the transactional email template with status active. Used to copy only its content fetched from htmlContent/htmlUrl to an email campaign for RSS feature.
scheduledAt	String	Sending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). Prefer to pass your timezone in date-time format for accurate result. If sendAtBestTime is set to true, your campaign will be sent according to the date passed (ignoring the time part)	2017-06-01T12:30:00+02:00
subject	String	Subject of the campaign. Mandatory if abTesting is false. Ignored if abTesting is true.
previewText	String	Preview text or preheader of the email campaign
replyTo	String	Email on which the campaign recipients will be able to reply to
toField	String	To personalize the To Field. If you want to include the first name and last name of your recipient, add {FNAME} {LNAME}. These contact attributes must already exist in your Brevo account. If input parameter params used please use {{contact.FNAME}} {{contact.LNAME}} for personalization
recipients	Object	Segment ids and List ids to include/exclude from campaign
attachmentUrl	url	Absolute url of the attachment (no local file).
inlineImageActivation	boolean	Use true to embedded the images in your email. Final size of the email should be less than 4MB. Campaigns with embedded images can not be sent to more than 5000 contacts
mirrorActive	boolean	Use true to enable the mirror link
footer	String	Footer of the email campaign
header	String	Header of the email campaign
utmCampaign	String	Customize the utm_campaign value. If this field is empty, the campaign name will be used. Only alphanumeric characters and spaces are allowed
sendAtBestTime	boolean	Set this to true if you want to send your campaign at best time.

Responses:

Method	Description	Response body
201	successfully created	`{ "id": 5 }`
400	Bad request

CURL:

copy

curl -X POST \ 
    {{baseUrl}}/v3/emailCampaigns \ 
    -H 'Content-Type: application/json' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "tag": "{{Tag}}",
        "sender": {
            "name": "digo",
            "email": "digo@sib.digo.link"
        },
        "name": "{{Campaign Name}}",
        "htmlContent": "{{Html content}}",
        "subject": "{{Subject}}",
        "replyTo": "{{Reply To}}",
        "toField": "{{toField}}",
        "recipients": {
            "listIds": [{{List Id}}]
        }
    }'

Example:

copy

curl -X POST \ 
    {{baseUrl}}/v3/emailCampaigns \ 
    -H 'Content-Type: application/json' \ 
    -H 'Host: api.apigw.tatacommunications.com' \ 
    -H 'api-key: {{api-key}}' \ 
   \ 
    -d '{
        "tag": "Newsletter",
        "sender": {
            "name": "Mary from MyShop",
            "email": "newsletter@myshop.com",
            "id": 3
        },
        "name": "Newsletter - May 2017",
        "htmlContent": "<!DOCTYPE html> <html> <body> <h1>Confirm you email</h1> <p>Please confirm your email address by clicking on the link below</p> </body> </html>",
        "htmlUrl": "https://html.domain.com",
        "templateId": 0,
        "scheduledAt": "2017-06-01T12:30:00+02:00",
        "subject": "Discover the New Collection !",
        "previewText": "Thanks for your order!",
        "replyTo": "support@myshop.com",
        "toField": "{FNAME} {LNAME}",
        "recipients": {
            "exclusionListIds": [
                8
            ],
            "listIds": [
                32
            ],
            "segmentIds": [
                23
            ]
        },
        "attachmentUrl": "https://attachment.domain.com",
        "inlineImageActivation": true,
        "mirrorActive": true,
        "footer": "[DEFAULT_FOOTER]",
        "header": "[DEFAULT_HEADER]",
        "utmCampaign": "NL_05_2017",
        "params": {
            "FNAME": "Joe",
            "LNAME": "Doe"
        },
        "sendAtBestTime": true
    }'

Get an email campaign report

GET: /v3/emailCampaigns/{campaignId}

Path Params:

Param	Type	Description	Example
campaignId	Integer	Id of the campaign	49

Query Params:

Param	Type	Description	Example
statistics	string	Filter on the type of statistics required.	globalStats, linksStats, statsByDomain, statsByDevice statsByBrowser

Responses:

Method	Description	Response body
200	Email campaign informations
400	Bad request
404	Campaign ID not found

CURL:

copy

curl -X GET \
    '{{baseUrl}}/v3/emailCampaigns/{{Campaign_Id}}' \
    -H 'Host: api.apigw.tatacommunications.com' \
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \
    '{{baseUrl}}/v3/emailCampaigns/49' \
    -H 'Host: api.apigw.tatacommunications.com' \
    -H 'api-key: {{api-key}}' \

Report

Get email delivery report

This endpoint will show the aggregated stats for past 30 days by default if startDate and endDate OR days is not passed. The date range can not exceed 90 days

GET: /v3/smtp/statistics/reports

Query Params:

Param	Type	Description	Example
Limit	Integer	Number of documents returned per page	2500
offset	Integer	Index of the first document in the page	0
startDate	String	Mandatory if endDate is used. Starting date of the report (YYYY-MM-DD)
endDate	String	Mandatory if startDate is used. Ending date of the report (YYYY-MM-DD)
Days	Integer	Number of days in the past including today (positive integer). Not compatible with ‘startDate’ and ‘endDate’
email	String	Filter the report for a specific email addresses
event	String	Filter the report for a specific event type
tags	String	Filter the report for tags (serialized and urlencoded array)
messageId	String	Filter on a specific message id
templateId	Integer	Filter on a specific template id
sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc, asc

Responses:

Method Description Response body

200

Email events report informations

Method	Description	Response body
200	Email events report informations	{ "events": [ { "email": "john.smith@example.com", "date": "2017-03-12T12:30:00Z", "messageId": "<201798300811.5787683@example.domain.com>", "event": "deferred", "reason": "Error connection timeout", "tag": "OrderConfirmation", "from": "john@example.com", "templateId": 4 }, { "email": "john.smith@example.com", "date": "2017-03-13T16:30:00Z", "messageId": "<201798300811.5787683@example.domain.com>", "event": "delivered", "tag": "OrderConfirmation", "from": "john@example.com", "templateId": 5 } ] }
400	Bad request


{
    "events": [
        {
            "email": "john.smith@example.com",
            "date": "2017-03-12T12:30:00Z",
            "messageId": "<201798300811.5787683@example.domain.com>",
            "event": "deferred",
            "reason": "Error connection timeout",
            "tag": "OrderConfirmation",
            "from": "john@example.com",
            "templateId": 4
        },
        {
            "email": "john.smith@example.com",
            "date": "2017-03-13T16:30:00Z",
            "messageId": "<201798300811.5787683@example.domain.com>",
            "event": "delivered",
            "tag": "OrderConfirmation",
            "from": "john@example.com",
            "templateId": 5
        }
    ]
}

400 Bad request

CURL:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/statistics/events?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&messageId=messageId' \  
    -H 'Host: api.apigw.tatacommunications.com' \ 
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/statistics/events?startDate=2023-10-04&endDate=2023-10-05&messageId=%3C202310041024.79880091500@smtp-relay.mailin.fr%3E' \ 
    -H 'Host: api.apigw.tatacommunications.com' \ 
    -H 'api-key: {{api-key}}' \

Get the list of transactional emails with filter like templateId, email, messageId

This endpoint will show the list of emails for past 30 days by default. To retrieve emails before that time, please pass startDate and endDate in query filters.

GET: /v3/smtp/emails

Query Params:

Param	Type	Description	Example
email	String	Mandatory if templateId and messageId are not passed in query filters. Email address to which transactional email has been sent.
templateId	Integer	Mandatory if email and messageId are not passed in query filters. Id of the template that was used to compose transactional email.
messageId	String	Mandatory if templateId and email are not passed in query filters. Message ID of the transactional email sent.
startDate	String	Mandatory if endDate is used. Starting date (YYYY-MM-DD) from which you want to fetch the list. Maximum time period that can be selected is one month.
endDate	String	Mandatory if startDate is used. Ending date (YYYY-MM-DD) till which you want to fetch the list. Maximum time period that can be selected is one month.
sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc, asc
Limit	Integer	Number of documents returned per page	500
offset	Integer	Index of the first document in the page	0

Responses:

Method Description Response body

201

List of transactional emails

Method	Description	Response body
201	List of transactional emails	`{ "count": 120, "transactionalEmails": [ { "email": "abc@xyz.com", "subject": "summer camp", "templateId": 15, "messageId": "<201798300811.5787683@relay.domain.com>", "uuid": "5a78c-209ok98262910-std2341", "date": "2019-05-25T11:53:26Z" }, { "email": "test@test.com", "subject": "details verification", "templateId": 15, "messageId": "<201798300811.5700093@relay.domain.com>", "uuid": "5a78c-209ok98262910-s99a341", "date": "2019-05-25T07:28:11Z" } ] }`
400	Bad request


{
    "count": 120,
    "transactionalEmails": [
        {
            "email": "abc@xyz.com",
            "subject": "summer camp",
            "templateId": 15,
            "messageId": "<201798300811.5787683@relay.domain.com>",
            "uuid": "5a78c-209ok98262910-std2341",
            "date": "2019-05-25T11:53:26Z"
        },
        {
            "email": "test@test.com",
            "subject": "details verification",
            "templateId": 15,
            "messageId": "<201798300811.5700093@relay.domain.com>",
            "uuid": "5a78c-209ok98262910-s99a341",
            "date": "2019-05-25T07:28:11Z"
        }
    ]
}

400 Bad request

CURL:

copy

curl -X GET \
    '{{baseUrl}}/v3/smtp/emails?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&templateId={{template_Id}}&email={{Email_Id}}' \ 
    -H 'Host: api.apigw.tatacommunications.com' \
    -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/emails?sort=desc&limit=500&offset=0' \ 
    -H 'Host: api.apigw.tatacommunications.com' \ 
    -H 'api-key: {{api-key}}' \

Get your transactional email activity aggregated per day

GET: /v3/smtp/statistics/reports

Query Params:

Param	Type	Description	Example
Limit	Integer	Number of documents returned per page	10
offset	Integer	Index of the first document in the page	0
startDate	String	Mandatory if endDate is used. Starting date of the report (YYYY-MM-DD)
endDate	String	Mandatory if startDate is used. Ending date of the report (YYYY-MM-DD)
days	Integer	Number of days in the past including today (positive integer). Not compatible with ‘startDate’ and ‘endDate’
tag	String	Tag of the emails
	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc, asc

Responses:

Method Description Response body

200

Aggregated report informations

Method	Description	Response body
200	Aggregated report informations	`{ "reports": [ { "date": "2017-04-30", "requests": 10756, "delivered": 10103, "hardBounces": 21, "softBounces": 137, "clicks": 1026, "uniqueClicks": 720, "opens": 5091, "uniqueOpens": 2318, "spamReports": 0, "blocked": 519, "invalid": 1, "unsubscribed": 0 } ] }`
400	Bad request


{
    "reports": [
        {
            "date": "2017-04-30",
            "requests": 10756,
            "delivered": 10103,
            "hardBounces": 21,
            "softBounces": 137,
            "clicks": 1026,
            "uniqueClicks": 720,
            "opens": 5091,
            "uniqueOpens": 2318,
            "spamReports": 0,
            "blocked": 519,
            "invalid": 1,
            "unsubscribed": 0
        }
    ]
}

400 Bad request

CURL:

copy

curl -X GET \ 
    {{baseUrl}}/v3/smtp/statistics/reports \ 
    -H 'Host: api.apigw.tatacommunications.com' \ 
    -H 'api-key: {{api-key}}' \

Get transactional email report for a period of time

GET: /v3/smtp/statistics/aggregatedReport

Query Params:

Param	Type	Description
startDate	String	Mandatory if endDate is used. Starting date of the report (YYYY-MM-DD) .. Must be lower than equal to endDate
endDate	String	Mandatory if startDate is used. Ending date of the report (YYYY-MM-DD). Must be greater than equal to startDate
days	Integer	Number of days in the past including today (positive integer). Not compatible with ‘startDate’ and ‘endDate’
tag	String	Tag of the emails

Responses:

Method Description Response body

200

Aggregated report informations

Method	Description	Response body
200	Aggregated report informations	`{ "range": "2016-09-08\|2017-04-28", "requests": 19887, "delivered": 18996, "hardBounces": 234, "softBounces": 1533, "clicks": 9987, "uniqueClicks": 8766, "opens": 17654, "uniqueOpens": 13688, "spamReports": 1, "blocked": 2, "invalid": 0, "unsubscribed": 2 }`
400	Bad request


{
    "range": "2016-09-08|2017-04-28",
    "requests": 19887,
    "delivered": 18996,
    "hardBounces": 234,
    "softBounces": 1533,
    "clicks": 9987,
    "uniqueClicks": 8766,
    "opens": 17654,
    "uniqueOpens": 13688,
    "spamReports": 1,
    "blocked": 2,
    "invalid": 0,
    "unsubscribed": 2
}

400 Bad request

CURL:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/statistics/aggregatedReport?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD' \  
      -H 'Host: api.apigw.tatacommunications.com' \ 
      -H 'api-key: {{api-key}}' \

Example:

copy

curl -X GET \ 
    '{{baseUrl}}/v3/smtp/statistics/aggregatedReport?startDate=2023-10-04&endDate=2023-10-05' \ 
      -H 'Host: api.apigw.tatacommunications.com' \ 
      -H 'api-key: {{api-key}}' \