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.

Processed status

The following response is an example of email request 'processed' but not yet delivered.

The 'processed' status indicates that the email is processed by the email server and submitted to the gateway, pending further processing.

{
    "data": [
        {
            "message_id": "4d0cc5e0-8324-4042-b65e-20d03420bf0d:1",
            "from_mail": "[email protected]",
            "request_datetime": "2022-01-05 05:36:47",
            "recipients": [
                {
                    "delivery_datetime": "",
                    "to": "[email protected]",
                    "status": "PROCESSED",
                    "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

The following response is an example of email request 'delivered' for a recipient and 'processed' for another recipient.

{
    "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": "PROCESSED",
                    "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": {}
}

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

πŸ“˜

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,
                        "processed": 9,
                        "submitted": 0
                    }
                }
            ]
        },
        {
            "date": "2022-01-12",
            "stats": [
                {
                    "metrics": {
                        "blocks": 0,
                        "deferred": 0,
                        "delivered": 0,
                        "opens": 0,
                        "processed": 3,
                        "submitted": 0
                    }
                }
            ]
        },
        {
            "date": "2022-01-19",
            "stats": [
                {
                    "metrics": {
                        "blocks": 0,
                        "deferred": 0,
                        "delivered": 0,
                        "opens": 0,
                        "processed": 6,
                        "submitted": 0
                    }
                }
            ]
        }
    ],
    "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,
                        "processed": 13
                    }
                }
            ]
        },
        {
            "date": "2022-01-11",
            "stats": [
                {
                    "metrics": {
                        "blocks": 0,
                        "deferred": 0,
                        "delivered": 0,
                        "opens": 0,
                        "processed": 9,
                        "submitted": 0
                    }
                }
            ]
        }
    ],
    "error": {}
}

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,
                        "processed": 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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "",
            "message_id": "75c48c25-092e-4796-af60-76aadc434002:2",
            "company_id": "Z*****d",
            "status": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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": "SUBMISSION",
            "description": "Message is successfully processed.",
            "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 is delivery is successful.

{
    "data": [
        {
            "message_id": "36004571-a131-4cc1-95a5-ddf7d89676c3:1",
            "company_id": "Zf7d36fbcsgc",
            "status": "DELIVERED",
            "description": "Message is successfully delivered.",
            "from_mail": "[email protected]",
            "to_mail": "[email protected]",
            "template_name": "Sample Testing new template",
            "submitted_at": "2022-08-25 06:45:17",
            "delivered_at": "2022-08-25 06:45:20",
            "sale_price": 1,
            "source": "API",
            "source_type": "API",
            "user_details": {},
            "email_body": "",
            "service_id": "",
            "route": ""
        }
    ],
    "error": {},
    "total": 1,
    "limit": "50",
    "offset": ""
}

Did this page help you?