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 – Multi Factor Authentication
Authenticate – One Tap Authentication
Engage
WhatsApp
Programmable Voice(India)
Email
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 Template Email Campaign Report

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 

{
    "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 

{
    "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 

{
    "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}}' \

What’s New