Metrics and filters
Metrics
The following are the API metrics you can retrieve over Metrics API. You can specify metrics to fetch specific performance indicators such as total traffic count, click rates, delivery success rates, and more. They provide valuable insights to monitor and optimize your strategies effectively.
| Delivery | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Total traffic |
TOTAL_TRAFFIC_COUNT |
The total number of messages or message segments (parts) sent to your customers (outbound) and messages received from your customers (inbound).
Channel specifics:
- Includes emails accepted by Infobip for delivery (not rejected). |
| Total SMS messages |
TOTAL_SMS_MESSAGES_COUNT |
The total number of SMS messages sent to and received from customers (inbound and outbound).
Messages split into multiple segments due to length are counted as a single distinct message.
Channel specifics:
- Retrievable only for SMS. |
| Total sent | TOTAL_SENT_TRAFFIC_COUNT |
The total number of messages submitted for delivery (outbound).
Channel specifics:
- When it comes to our Email service, this refers to the toal number of emails sent from our platform to the mailbox provider. |
| Delivered |
DELIVERED_TRAFFIC_COUNT |
The total number of messages delivered to a recipient. |
| Delivery rate |
TRAFFIC_DELIVERY_RATE |
The percentage of messages successfully delivered to recipients. |
| 5 sec delivery rate |
TRAFFIC_DELIVERED_IN_5_SEC_RATE |
The percentage of messages delivered within a 5-second time frame. |
| Delivery failure | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Failed |
FAILED_TRAFFIC_COUNT |
The total number of sent (outbound) messages not delivered to a recipient. |
| Bounced |
TOTAL_BOUNCE_COUNT |
The total number of emails not delivered to recipients, including soft bounces (temporary issue) and hard bounces (permanent issue).
Channel specifics:
- Retrievable only for Email. |
| Bounce rate |
TOTAL_BOUNCE_RATE |
The percentage of emails that were not delivered to recipients' inboxes. This includes both soft and hard bounces. It is calculated by summing up soft bounced and hard bounced messages, and dividing them by the number of messages sent (Total sent).
Channel specifics:
- Retrievable only for Email. |
| Dropped |
TOTAL_DROPPED_COUNT |
The submitted emails that were dropped before the delivery due to various reasons. For example, the recipient unsubscribed, address bounced, the message was marked as spam, or sender errors such as blocked or unverified domain, or content-related issues such as expired templates or too many URLs.
Channel specifics:
- Retrievable only for Email. |
| Dropped rate |
TOTAL_DROPPED_RATE |
The percentage calculated by dividing the number of dropped emails by the number of accepted emails.
Channel specifics:
- Retrievable only for Email. |
| Suppressed |
TOTAL_SUPPRESSED_COUNT |
The number of emails that were not sent due to a bounce or a negative recipient reaction (marking the email as spam).
Channel specifics:
- Retrievable only for Email. |
| Soft bounced |
SOFT_BOUNCE_COUNT |
The number of emails temporarily undeliverable to recipients. This can happen due to the recipient's inbox being full, the domain temporarily unavailable, or the mailbox provider suspecting legitimacy or lack of recipient opt-in.
Channel specifics:
- Retrievable only for Email. |
| Soft bounce rate |
SOFT_BOUNCE_RATE |
The percentage of emails temporarily undeliverable to recipients. It is calculated by dividing the number of soft bounced messages by the number of messages sent (Total sent).
Channel specifics:
- Retrievable only for Email. |
| Hard bounced |
HARD_BOUNCE_COUNT |
The number of emails that received a permanent error from mailbox providers when attempting to deliver the email to a specific recipient.
Channel specifics:
- Retrievable only for Email. |
| Hard bounce rate |
HARD_BOUNCE_RATE |
The percentage of emails permanently undeliverable to recipients. It is calculated by dividing the number of hard bounced messages by the number of messages sent (Total sent).
Channel specifics:
- Retrievable only for Email. |
| Inbound | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Received traffic |
TOTAL_SENT_TRAFFIC_COUNT |
The total number of messages you received from customers (inbound).
Channel specifics:
This metric may not provide data for messaging channels that do not support inbound messaging or if receiving inbound messages is not configured on the Infobip platform. |
| Received to sent ratio |
RECEIVED_TO_SENT_TRAFFIC_RATIO |
Ratio of received (inbound) to sent (outbound) messages that were not rejected.
Channel specifics:
This metric may not provide data for messaging channels that do not support inbound messaging or if receiving inbound messages is not configured on the Infobip platform. |
| Seen/Opened | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Seen/Unique Opens |
SEEN_OPENED_TRAFFIC_COUNT |
The number of messages that were seen or opened by recipients.
Channel specifics:
This metric may not provide data for messaging channels that do not support the seen callback feature. It is designed to capture engagement metrics only for supported platforms such as WhatsApp, Viber, and RCS.
For Email, we are returning the count of unique open messages. |
| Seen/Unique opens rate |
SEEN_OPENED_TRAFFIC_RATE |
The percentage of messages that were seen or opened by recipients.
Channel specifics:
This metric may not provide data for messaging channels that do not support the seen callback feature. It is designed to capture engagement metrics only for supported platforms such as WhatsApp, Viber, and RCS.
For Email, we are returning the rate of unique open messages. |
| Opens |
VIEWED_TOTAL_COUNT |
The number of open messages per single email address. The emails opened multiple times by the same recipient are also counted.
Channel specifics:
- Retrievable only for Email. |
| Open rate |
VIEWED_TOTAL_RATE |
The percentage of recipients who opened an email campaign.
Channel specifics:
- Retrievable only for Email. |
| Clicks/Engagement | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Traffic clicked |
CLICKED_TRAFFIC_COUNT |
The number of sent (outbound) messages where at least one URL was clicked.
Channel specifics:
This metric may not return values under the following circumstances:
- Data is only captured if the shortening and tracking functionality is enabled when sending messages through Infobip's SaaS products/tools or API.
- Tracking may not be available for all channels, for example Apple Messages for Business or Messenger. Please check the full list.
For Email, we are taking into the consideration only unique clicks. |
| Total clicks count | TOTAL_CLICKS_COUNT
|
The total number of clicks.
Channel specifics:
This metric may not return values under the following circumstances:
- Data is only captured if the shortening and tracking functionality is enabled when sending messages through Infobip's SaaS tools or API.
- Tracking may not be available for all channels, for example Apple Messages for Business or Messenger. Please check the full list.
For Email, we count the number of clicks per email. We count every URL click except the unsubscribe link. |
| Click rate |
TRAFFIC_CLICK_RATE |
The percentage of messages containing a clicked URL.
Channel specifics:
This metric may not return values under the following circumstances:
- Data is only captured if the shortening and tracking functionality is enabled when sending messages through Infobip's SaaS tools or API.
- Tracking may not be available for all channels, for example Apple Messages for Business or Messenger. Please check the full list.
For Email, we return the percentage of recipients who clicked on a link within an email campaign. |
| Clicks per URL |
CLICKED_URL_COUNT |
The number of clicks per specific URL.
Channel specifics:
This metric may not return values under the following circumstances:
- Data is only captured if the shortening and tracking functionality is enabled when sending messages through Infobip's SaaS tools or API.
- Tracking may not be available for all channels, for example Apple Messages for Business or Messenger. Please check the full list.
- Not retrievable for Email. |
| Email click rate |
TOTAL_CLICK_RATE |
The percentage of recipients who clicked on a link within an email campaign.
Channel specifics:
- Retrievable only for Email. |
| Click to open rate |
CLICK_TO_OPEN_RATE |
The percentage of total unique clicks (one or more clicks per single email counts as a unique click) divided by the number of total unique opened messages.
Channel specifics:
- Retrievable only for Email. |
| Feedback | ||
|---|---|---|
| Metrics name | API syntax | Description |
| Unsubscribes |
UNSUBSCRIBED_TRAFFIC_COUNT |
The number of recipients who unsubscribed (opted out) from future communications sent from the sending address.
Channel specifics:
- Retrievable only for Email. |
| Unsubscribe rate |
UNSUBSCRIBED_TRAFFIC_RATE |
The percentage of recipients who unsubscribed (opted out) from future communications sent from the sending address.
Channel specifics:
- Retrievable only for Email. |
| Spam complaints |
EMAIL_COMPLAINTS_COUNT |
The number of emails that recipients reported as spam.
Channel specifics:
- Retrievable only for Email. |
| Spam complaints rate |
EMAIL_COMPLAINTS_RATE |
The percentage of emails that recipients reported as spam.
Channel specifics:
- Retrievable only for Email. |
Aggregation/Dimensions
You can view metrics in meaningful groupings. For example, total traffic counts become much more impactful when you view them for each sender, network, or country.
Our API provides extensive options (aggregateBy) for data aggregation, including grouping by time intervals, message status, and error types. This grouping functionality simplifies data analysis and aids in extracting meaningful insights from large datasets.
| Dimension name | Description |
|---|---|
|
HOUR |
Groups results by hour, showing corresponding timestamp values. |
|
DAY |
Groups results by day, showing corresponding day values. |
|
WEEK_SATURDAY_START |
Groups results by week starting from Saturday, showing corresponding timestamp values. |
|
WEEK_SUNDAY_START |
Groups results by week starting from Sunday, showing corresponding timestamp values. |
|
WEEK_MONDAY_START |
Groups results by week starting from Monday, showing corresponding timestamp values. |
|
MONTH |
Groups results by month, showing corresponding month values. |
|
QUARTER |
Groups results by quarter, showing corresponding quarter values. |
|
YEAR |
Groups results by year, showing corresponding year values. |
|
ACCOUNT_KEY |
Groups results by account key in the response, showing corresponding account key values. |
|
CHANNEL_CODE |
Groups results by channel, showing corresponding channel code values. |
|
CHANNEL_NAME |
Groups results by channel name, showing corresponding channel name values. |
|
STATUS_GROUP |
Groups results by status group, showing corresponding status group values of a response. |
|
STATUS |
Groups results by status name, showing corresponding status values of a response. |
|
ERROR_GROUP |
Groups results by error group, showing corresponding error group values of a response. |
|
ERROR_CODE |
Groups results by error code, showing their corresponding error code values of a response. |
|
TIME_TO_DELIVER |
Groups results by 'time to deliver' period, showing corresponding 'time to deliver' period description value. |
|
TIME_TO_CLICK_FROM_SEEN |
Groups results by the difference in time (sec) between a message click and seen events, showing the calculated values. |
|
TIME_TO_CLICK_FROM_DELIVERED |
Groups results by the difference in time (sec) between a message click and delivered events, showing the calculated values. |
|
TIME_TO_SEEN_FROM_DELIVERED |
Groups results by the difference in time (sec) between a message seen and delivered events, showing the calculated values. |
|
DIRECTION |
Groups results by the traffic direction, showing corresponding direction values: OUTBOUND for traffic sent to a client and INBOUND for traffic received from a client. |
|
SENDER |
Groups results by sender, showing corresponding sender values. |
|
SENDER_TYPE |
Groups results by sender type, showing corresponding sender type values. |
|
COMMUNICATION |
Groups results by communication, showing corresponding communication ID value. |
| CAMPAIGN_REFERENCE | Groups results by campaign reference, showing corresponding campaign reference ID value. |
|
NETWORK_ID |
Groups results by network, showing corresponding network ID values. |
|
NETWORK_NAME |
Groups results by network, showing corresponding network name values. |
|
COUNTRY_ID |
Groups results by country, showing corresponding country ID values. |
|
COUNTRY_NAME |
Groups results by country, showing corresponding country name values. |
|
APPLICATION_ID |
Groups results by application, showing corresponding application ID values. |
|
ENTITY_ID |
Groups results by entity, showing corresponding entity ID values. |
|
URL |
Groups results by the initial URL from a message, showing corresponding URL values.
Please note that you cannot use aggregateBy URL with the non-URL measures. CLICKED_URL_COUNT would be valid, while TOTAL_TRAFFIC_COUNT would NOT be valid. |
|
TRAFFIC_TYPE |
Groups results by traffic type, showing corresponding traffic type values. |
Filters
Customize your queries with an array of filtering options to limit results by specific characteristics. With this flexibility, you can retrieve your data according to your specific requirements.
| Filter name | API syntax | Description | Required |
|---|---|---|---|
| Accounts |
accountKeys |
Targets specific accounts based on accountKeys.
Restrictions apply for legacy accounts. |
No |
| Sub-accounts |
includeSubaccounts |
Includes subaccount traffic data for comprehensive analysis. | No |
| Sent time range |
sentSince |
Includes a specific message time frame. | Yes |
|
sentUntil |
|||
| Engagement timeframe |
timeToDeliver |
Represents the time within which a message is delivered using time buckets. For instance, you can filter only messages delivered within 1 second. The from bucket is inclusive, while the to bucket is exclusive. |
No |
|
timeToClickFromSeen |
Represents the time within which a URL is clicked after the message is seen using time buckets. For example, you can filter only messages whose URLs were clicked within 1 second after they were seen. The from bucket is inclusive, while the to bucket is exclusive. |
No | |
|
timeToClickFromDelivered |
Represents the time within which a URL is clicked after the message is delivered using time buckets. For example, you can filter only messages whose URLs were clicked within 1 second after they were delivered. The from bucket is inclusive, while the to bucket is exclusive. |
No | |
|
timeToSeenFromDelivered |
Represents the time within which a message is seen after the message is delivered using time buckets. For example, you can filter only messages that were seen within 1 second after they were delivered. The from bucket is inclusive, while the to bucket is exclusive. |
No | |
| Statuses and error codes |
statusGroups |
Filter by specific status or error codes.
- List of possible general status codes.
- List of possible message statuses.
- List of possible error codes. |
No |
|
statuses |
No | ||
|
errorGroups |
No | ||
|
errorCodes |
No | ||
| Direction |
direction |
Categorizes traffic based on direction, distinguishing between outbound and inbound messages. |
No |
| Channel |
channelCode |
Categorizes traffic based on communication channels. | Yes |
| Traffic type |
trafficTypes |
List of possible traffic types. |
No |
| Sender |
senders |
Filters traffic based on specific senders or sender types. |
No |
| Sender type |
senderTypes |
No | |
| Communication ID |
communicationIds |
Categorizes traffic based on specific identifiers such as communication IDs. It is only applicable for traffic sent over Infobip SaaS solutions, such as Broadcast or Moments (Flow). |
No |
| Network |
networkIds |
Categorizes traffic based on specific identifiers, such as network IDs, or country IDs |
No |
| Country |
countryIds |
No | |
| Application |
applicationId |
By including additional CPaaSX parameters like applicationId and entityId, you can get valuable insights into the source and purpose of your communication activities, aiding in more accurate analysis and decision-making.
Use these parameters if you are using CPaaSX concepts and features.
Learn more about CPaaSX here. |
No |
| Entity |
entityId |
No |
Channels
The following is a list of available channels and services and their codes:
|
Channel code |
Channel name |
|---|---|
|
SMS |
SMS |
|
|
|
|
EMAILVALID |
Email validation |
|
FB |
Facebook Messenger |
|
GBM |
Google Business Messages |
|
IM |
Instagram Messaging |
|
KAKAOA |
Kakao Alim |
|
KAKAOC |
Kakao Chingu |
|
KAKAOS |
Kakao Sangdam |
|
LINELNS |
LINE LNS |
|
LINEOA |
LINE OA |
|
MMS |
MMS |
|
NL |
Number lookup |
|
RCS |
RCS |
|
TELEGRAM |
Telegram |
|
VIBER |
Viber Business Messages |
|
VIBERBOTS |
Viber Bots |
|
|
|
|
ZALOZNS |
Zalo |
|
APPLECB |
Apple Chat For Business |
trafficTypes
In messaging platforms like WhatsApp and RCS, traffic types categorize messages based on their nature and purpose, influencing how they are billed. For WhatsApp, traffic types include Marketing, Utility, Authentication, and Service Conversations, each with its distinct billing criteria. Meanwhile, RCS categorizes messages as Basic Transactions or Single Transactions. Familiarizing with these traffic types is essential for businesses to efficiently handle their messaging operations when interpreting the data associated with traffic types compared to regular, unassigned traffic.
| ID | Name | Description |
|---|---|---|
| 1 |
UTILITY_CONVERSATION |
WA Utility |
| 2 |
AUTHENTICATION_CONVERSATION |
WA Authentication |
| 3 |
MARKETING_CONVERSATION |
WA Marketing |
| 4 |
SERVICE_CONVERSATION |
WA Service |
| 5 |
BASIC_TRANSACTION_BASED_MESSAGE |
RCS basic transaction based message |
| 6 |
SINGLE_TRANSACTION_BASED_MESSAGE |
RCS single transaction based message |
senderTypes
The table below outlines various sender types available for messaging operations, each serving specific purposes and catering to different regions.
| ID | Name | Description | Special region |
|---|---|---|---|
| 1 |
NUMERIC |
Numeric | - |
| 2 |
ALPHANUMERIC |
Alpha | - |
| 3 |
SHORT_CODE |
Short | - |
| 4 |
TOLL_FREE_NUMBER |
Toll free number | North America |
| 5 |
TEXT_ENABLED_LANDLINE |
Text enabled landline | North America |
| 6 |
LONG_CODE_TEN_DLC |
Long code/10DLC | North America |
| 7 | - | - | - |
| 8 |
SC_STANDARD |
Shortcode standard | North America |
| 9 |
SC_FTEU |
Shortcode FTEU | North America |