Get stats and Get logs in Email API
View status of emails and the logs of the emails sent for a date range.
The email APIs in this page show the different statuses of the emails sent and the logs for all the emails sent within the specified date range.
Get stats by message ID
Using message ID, you can get a detailed information about an email sent.
Use the following 'GET' method to view the different statuses of an email.
Base URL
<https://api.kaleyra.io/v1/><SID>/email/stats/<message id>
The different statuses of an email are described in the following sections.
Accepted status
A request is marked as ‘accepted’ once it gets validated successfully by Kaleyra.
{
"data": [
{
"message_id": "4d0cc5e0-8324-4042-b65e-20d03420bf0d:1",
"from_mail": "<your from address>",
"request_datetime": "2022-01-05 05:36:47",
"recipients": [
{
"delivery_datetime": "",
"to": "[email protected]",
"status": "ACCEPTED",
"error_code": "",
"error_message": ""
}
]
}
],
"error": {}
}
Bounce status
The following response is an example of email request 'bounced'.
{
"data": [
{
"message_id": "a23228e1-a500-4948-82d9-ec4c55025d43:1",
"from_mail": "[email protected]",
"request_datetime": "2022-01-11 10:11:27",
"recipients": [
{
"delivery_datetime": "2022-01-11 10:11:31",
"to": "[email protected]",
"status": "BOUNCE",
"error_code": "550",
"error_message": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/?p=NoSuchUser h127si1000977wmh.173 - gsmtp\""
}
]
}
],
"error": {}
}
Delivered status
A request will be marked as ‘delivered’ when the email is delivered to the recipient’s mailbox through the service provider.
The following response is an example of an email request 'delivered' for a recipient and 'accepted' for another recipient.
JSON
{
"data": [
{
"message_id": "5c1ef0ec-3849-4e1d-9a7e-74f85a579468:1",
"from_mail": "[email protected]",
"request_datetime": "2022-01-11 10:10:42",
"recipients": [
{
"delivery_datetime": "2022-01-11 10:10:47",
"to": "[email protected]",
"status": "DELIVERED",
"error_code": "",
"error_message": ""
},
{
"delivery_datetime": "",
"to": "[email protected]",
"status": "ACCEPTED",
"error_code": "",
"error_message": ""
}
]
}
],
"error": {}
}
Blocked status
The 'blocked' status indicates that the email is being sent from an invalid sender domain (not registered).
The following response is an example of email request 'blocked' due to invalid sender domain.
{
"data": [
{
"message_id": "6d71ce19-4ec1-41e7-ab91-acc476c3e0c2:1",
"from_mail": "[email protected]",
"request_datetime": "2022-01-11 10:07:30",
"recipients": [
{
"delivery_datetime": "",
"to": "[email protected]",
"status": "BLOCKED",
"error_code": "",
"error_message": "invalid sender domain"
}
]
}
],
"error": {}
}
Note:
The error message "Message has not been delivered because sender domain is not whitelisted" is shown when the message delivery status is 'blocked'.
Get summary stats
Using a 'Get stats' by date range, you can get a summary of the statuses of all the emails that are sent. You can specify a date range as a query parameter to obtain the statuses of the emails sent within the specified date range. You can also use 'pagination' for the result.
Make sure to specify the date in the format: YYYY-MM-DD.
To get a response for email status from a specific start date:
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=<insert start date>
For example:
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=2022-01-12
To get a response for email status up to a specific end date:
<https://api.kaleyra.io/v1/><SID>/email/stats?end_date=<insert end date>
For example:
<https://api.kaleyra.io/v1/><SID>/email/stats?end_date=2022-01-12
In the following response example, the stats are obtained using the start date.
Note:
The date is considered according to the time zone of the user account.
For example:
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=2022-01-12
{
"data": [
{
"date": "2022-01-11",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 9,
}
}
]
},
{
"date": "2022-01-12",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 3,
}
}
]
},
{
"date": "2022-01-19",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 6,
}
}
]
}
],
"error": {}
}
The following response is obtained using start date and end date. All the email statuses within the specified date range are shown.
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=<insert start date>&end_date=<insert end date>
Example
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=2022-01-10&end_date=2022-01-12
{
"data": [
{
"date": "2022-01-10",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 13
}
}
]
},
{
"date": "2022-01-11",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 9,
}
}
]
}
],
"error": {}
}
Pagination
To specify both the start date and the end date along with pagination, use the following endpoint:
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=<insert start date>&end_date=<insert end date>&page=<insert page no>&limit<insert limit no>
The default value for limit is 50 and the maximum value is 100. The page number cannot have a zero or a negative value.
Example:
<https://api.kaleyra.io/v1/><SID>/email/stats?start_date=2022-01-10&end_date=2022-01-12&page=1&limit=1
{
"data": [
{
"date": "2022-01-10",
"stats": [
{
"metrics": {
"blocks": 0,
"deferred": 0,
"delivered": 0,
"opens": 0,
"accepted": 13
}
}
]
}
],
"error": {}
}
Get Logs APIs
The email API logs show a detailed information about the sent messages such as, recipient email address, delivery status, description, route, source, date & time, message ID, from address, cost, and template name/text body.
To obtain logs from a start date using an API request, use the following end point:
<https://api.kaleyra.io/v1/><SID>/email/logs?start_date=<insert start date>
Example:
<https://api.kaleyra.io/v1/><SID>/email/logs?start_date=2022-01-12
A sample response body is shown.
{
"data": [
{
"message_id": "d00808f2-8e3d-4a02-aa06-62b03f24796a:1",
"company_id": "Z*****d",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "<your from address>",
"to_mail": "[email protected],[email protected]",
"template_name": "",
"submitted_at": "2022-08-04 14:20:33",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "75c48c25-092e-4796-af60-76aadc434002:2",
"company_id": "Z*****d",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "<your from address>",
"to_mail": "[email protected],[email protected]",
"template_name": "",
"submitted_at": "2022-08-04 14:16:15",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "75c48c25-092e-4796-af60-76aadc434002:1",
"company_id": "Z*****d",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "<your from address>",
"to_mail": "[email protected],[email protected]",
"template_name": "",
"submitted_at": "2022-08-04 14:16:15",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "64156a40-2fbb-4595-ba6c-d1eaa2802a3f:1",
"company_id": "Z*****d",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "<your from address>",
"to_mail": "[email protected],[email protected]",
"template_name": "",
"submitted_at": "2022-08-04 14:16:04",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
}
],
"error": {},
"total": 4,
"limit": "50",
"offset": ""
}
To obtain the logs using start date and end date, use the following end points. All the logs within provided date range will be obtained. Format of date must be YYYY-MM-DD.
<https://api.kaleyra.io/v1/><SID>/email/logs?start_date=<insert start date>&end_date=<insert end date>
Example:
<https://api.kaleyra.io/v1/><SID>/email/logs?start_date=2022-01-10&end_date=2022-01-12
The Response body is shown.
{
"data": [
{
"message_id": "9be5abb2-5d98-477e-b09d-93f9cc971247:2",
"company_id": "Z******",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "insert your from address",
"to_mail": "iam*******[email protected]",
"template_name": "",
"submitted_at": "2022-07-21 11:52:43",
"delivered_at": "",
"sale_price": 1,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "9be5abb2-5d98-477e-b09d-93f9cc971247:1",
"company_id": "Z******",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "insert your from address",
"to_mail": "a*******@gmail.com",
"template_name": "",
"submitted_at": "2022-07-21 11:52:43",
"delivered_at": "",
"sale_price": 1,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "3bcb5453-088e-4489-8f6f-228b63995bff:2",
"company_id": "Z******",
"status": "FAILED",
"description": "Message has not been processed because maybe due to internal server error or due to insufficient balance.",
"from_mail": "insert your from address",
"to_mail": "iam*******[email protected]",
"template_name": "",
"submitted_at": "2022-07-21 11:52:00",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "3bcb5453-088e-4489-8f6f-228b63995bff:1",
"company_id": "Z******",
"status": "FAILED",
"description": "Message has not been processed because maybe due to internal server error or due to insufficient balance.",
"from_mail": "insert your from address",
"to_mail": "a*******@gmail.com",
"template_name": "",
"submitted_at": "2022-07-21 11:52:00",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
}
],
"error": {},
"total": 16,
"limit": "4",
"offset": ""
}
To obtain logs using the recipient mail ID and the start date, use the following end point:
<https://api.kaleyra.io/v1/><SID>/email/logs?toMail=<insert recipient>&start_date=<insert date>
Example:
<https://api.kaleyra.io/v1/><SID>/email/[email protected]&start_date=2022-01-12
The Response body is shown.
{
"data": [
{
"message_id": "a12a270d-acee-4554-87da-0106f8967c54:2",
"company_id": "Z*****dd",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "your from address",
"to_mail": "iam*****@gmail.com",
"template_name": "",
"submitted_at": "2022-08-02 11:32:28",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
},
{
"message_id": "5313e5b3-4516-4f84-bd08-d3ecf4d31515:2",
"company_id": "Z*****dd",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "your from address",
"to_mail": "iam*****@gmail.com",
"template_name": "",
"submitted_at": "2022-08-02 11:31:31",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
}
],
"error": {},
"total": 10,
"limit": "2",
"offset": ""
}
To obtain the logs using the message id and the end date, use the following end points:
<https://api.kaleyra.io/v1/><SID>/email/logs?messageId=<insert message id>&end_date=<insert date>
Example:
<https://api.kaleyra.io/v1/><SID>/email/logs?messageId=a12a270d-acee-4554-87da-0106f8967c54:2&end_date=2022-01-12
Note:
- The sale_price parameter indicates the money charged(deducted) from the account for the email service when the email delivery is successful for prepaid connections.
When an email delivery status is updated as ‘FAILED’, the ‘refund API’ request is triggered in order to refund the email service charges.- When the account balance money is less than the email charges to be deducted for the current email to be sent to a recipient, then an error message "Message has not been processed because maybe due to internal server error or due to insufficient balance" is shown for prepaid connections.
- When a template used in the Email API is not approved, then the message "Message has not been delivered because template is not approved or deleted" is shown.
{
"data": [
{
"message_id": "a12a270d-acee-4554-87da-0106f8967c54:2",
"company_id": "Z*****dd",
"status": "ACCEPTED",
"description": "Message is accepted.",
"from_mail": "[email protected]",
"to_mail": "i************[email protected]",
"template_name": "",
"submitted_at": "2022-08-02 11:32:28",
"delivered_at": "",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": ""
}
],
"error": {},
"total": 1,
"limit": "50",
"offset": ""
}
Search feature in Get Logs APIs
You can also use the ‘search’ feature to obtain specific emails in the log APIs. You can search based on
“from:” address, “to:” address, template name, delivery status parameters.
Examples of log APIs with search parameters:
Use the GET method:
- https://api.kaleyra.io/v1//email/logs?search=[email protected] - Search on the to mail parameter
- https://api.kaleyra.io/v1//email/logs?search=DELIVERED - Search on the delivery status.
Note:
The delivery statuses of an email are:
‘BLOCKED’, ‘BOUNCE, ‘DEFERRED’, ‘DELIVERED’, ‘ACCEPTED’ , ‘FAILED’ ,’OPEN’, ‘SUPPRESSED’.It is not case sensitive when you use it in the Get Log APIs.
- https://api.kaleyra.io/v1//email/logs?search=new_template - Search on the template name
- https://api.kaleyra.io/v1//email/logs?search=[email protected] - Search based on from address.
Note:
The search parameter searches in both the 'from' and 'to' values, and if it finds a match, it displays the result.
You can also use the pagination feature along with the search feature in the log APIs.To know more about the pagination feature, see: Pagination
You can add more than one query parameter in the same search request.
Example 1: single search condition
Below is an example of a search parameter in the Get Logs API to fetch all the emails with the ‘BOUNCE’ status
https://api.kaleyra.io/v1//email/logs?search=BOUNCE
Example 2: multiple search conditions
Below is an example of a search parameter in the Get Logs API to fetch all the emails with status = ‘DELIVERED’ status and to_mail = ‘[email protected]’
https://api.kaleyra.io/v1/>/email/logs?search=DELIVERED&search=[email protected]
A sample response body for Example 1 is shown.
{
"data": [
{
"message_id": "0f9ea4e0-d23a-47d8-8f72-ecf08b03afda:1",
"company_id": "Z97318f0incd",
"status": "BOUNCE",
"description": "Message has not been delivered maybe because of wrong email address or the recipient's inbox is full or a connection timeout from the sender’s domain.",
"from_mail": "[email protected]",
"to_mail": "[email protected]",
"template_name": "",
"submitted_at": "2023-06-01 04:59:34",
"delivered_at": "2023-06-01 04:59:36",
"sale_price": 0,
"source": "API",
"source_type": "API",
"user_details": {},
"email_body": "",
"service_id": "",
"route": "",
"type": "MKT"
}
],
"error": {},
"total": 1,
"limit": "50",
"page": "0"
}
Updated 11 months ago