Metrics and filters

The Metrics API provides comprehensive tools for analyzing your communication campaigns. By combining metrics and filters, you can gain deeper insights into performance indicators and tailor your queries to meet specific analysis needs. Metrics measure key aspects such as delivery success rates, traffic counts, and engagement levels, while filters allow you to refine the data by channel, time, traffic type, or sender. Together, they enable detailed reporting and optimization of messaging strategies.

Use filters to customize your queries and focus on specific characteristics like engagement timeframes or error codes. This flexibility ensures you can retrieve the most relevant data for your analysis and decision-making processes.

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).
Total accepted traffic	`TOTAL_ACCEPTED_TRAFFIC_COUNT`	The total number of accepted messages sent to your customers (outbound). Channel specifics: Retrievable only for Email.
Messaging interactions	`INTERACTION_COUNT`	Number of distinct messaging interactions. When combined with the `TRAFFIC_TYPE` dimension, it helps analyze specific messaging traffic by breaking down interactions into different WhatsApp or RCS categories, such as conversations or sessions.
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 total 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.

Inbound

Metrics name	API syntax	Description
Received traffic	`TOTAL_RECEIVED_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.

Delivery failure

Metrics name	API syntax	Description
Failed	`FAILED_TRAFFIC_COUNT`	The total number of sent (outbound) messages not delivered to a recipient. Channel specifics: Not retrievable for Email. Please use `TOTAL_DROPPED_COUNT` if interested in counts of messages that failed to deliver.
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 delivery due to various reasons, such as the recipient unsubscribed, address bounced, the message was marked as spam, or sender errors such as blocked or unverified domain, or content-related issues like 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 bounced 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 bounced 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.

Seen/Opened

Metrics name	API syntax	Description
Seen/Unique opens	`SEEN_OPENED_TRAFFIC_COUNT`	The number of messages that were seen or opened by unique recipients, counting each recipient only once regardless of how many times they opened the same message. Consider that recipients can turn off their read receipts, which can result in a lower seen count. 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 rate/Unique opens rate	`SEEN_OPENED_TRAFFIC_RATE`	The percentage of messages that were seen or opened by unique recipients. Consider that recipients can turn off their read receipts, which can result in a lower seen rate. 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
Unique clicks	`UNIQUE_CLICKS_COUNT`	The number of unique recipients who clicked on any link within a message, counting each recipient only once regardless of the number of links clicked in that message. 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 consideration only unique clicks.
Unique click-through rate	`UNIQUE_CLICK_THROUGH_RATE`	The percentage of unique recipients who clicked on a link compared to the total number of messages delivered, counting each recipient only once regardless of the number of links clicked in that message. 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 return the percentage of recipients who clicked on a link within an email campaign.
Unique clicked URLs	`UNIQUE_URL_CLICK_COUNT`	The number of unique URLs clicked in a single message. 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.
Click-to-open rate (CTOR)	`CLICK_TO_OPEN_RATE`	The percentage of recipients counted as unique clicks divided by unique opens or seens (each recipient is counted only once regardless of the number of links clicked in that message).
Total clicks	`TOTAL_CLICKS_COUNT`	The total number of clicks on all URLs within a single message, including multiple clicks on the same link. For example, if a message contains 3 links and each link is clicked twice, the total clicks count is 6. 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 count the number of clicks per email. We count every URL click except the unsubscribe link.
Click rate	`TOTAL_CLICK_RATE`	The percentage of recipients who clicked on any link, calculated as the total number of clicks across all URLs within a message divided by the total number of delivered messages. For instance, if 200 SMS messages are sent and there are 400 total clicks, the `TOTAL_CLICK_RATE` is 200%.

Feedback

Metrics name	API syntax	Description
Unsubscribes	`UNSUBSCRIBED_USER_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_USER_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
`ACCOUNT_KEY`	Groups results by account key in the response, showing corresponding account key values.
`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.
`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.
`CHANNEL_CODE`	Groups results by channel, showing corresponding channel code values.
`CHANNEL_NAME`	Groups results by channel name, showing corresponding channel name 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.
`TRAFFIC_TYPE`	Groups results by traffic type, showing corresponding traffic type values.
`SENDER`	Groups results by sender, showing corresponding sender values.
`SENDER_TYPE`	Groups results by sender type, showing corresponding sender type values.
`SENDER_DOMAIN`	Groups the results by sender domain showing corresponding sender domain values.
`RECIPIENT_DOMAIN`	Groups the results by recipient domain showing corresponding recipient domain 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. `UNIQUE_URL_CLICK_COUNT` would be valid, while `TOTAL_TRAFFIC_COUNT` would NOT be valid.
`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.
`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.

Forced aggregation by channel code

The CHANNEL_CODE dimension is always included in the results, regardless of whether it is specified in the aggregateBy parameter. This ensures the integrity and accuracy of the calculated metrics. For example, even if you request aggregation only by HOUR, the results will still include the CHANNEL_CODE dimension.
If neither CHANNEL_CODE nor CHANNEL_NAME is specified in the initial request, the CHANNEL_CODE dimension will be implicitly added to the results.
If you choose to aggregate by CHANNEL_NAME, the CHANNEL_CODE will not be added automatically. This allows clients the flexibility to have both values if needed.

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	API syntax	Description	Required
Accounts	`accountKeys`	Targets specific accounts based on accountKeys (opens in a new tab). Restrictions apply for legacy accounts.	No
Sub-accounts	`includeSubaccounts`	Includes subaccount traffic data for comprehensive analysis.	No
Sent time range	`sentSinces`	Includes a specific message time frame.	Yes
Sent time range	`sentUntil`	Includes a specific message time frame.	Yes
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.
	`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.
	`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.
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`
	`errorGroups`
	`errorCodes`
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 values for traffic types	No
Sender	`senders`	Filters traffic based on specific senders or sender types. List of possible values for 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
Campaign reference ID	`campaignReferenceIds`	Categorizes traffic based on specific identifiers such as campaign reference IDs. It is only applicable for traffic sent over Infobip APIs.	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. The Metrics API supports filtering data by multiple application and entity pairs within a single request. 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:

Dimension name	Description
SMS	SMS
EMAIL	Email
EMAILVALID	Email validation
FB	Facebook Messenger
IM	Instagram Messaging
KAKAOA	Kakao Alim
KAKAOC	Kakao Chingu
KAKAOS	Kakao Sangdam
LINELNS	LINE Official Notification
LINEOA	LINE Official Account
MMS	MMS
NL	Number lookup
RCS	RCS
TELEGRAM	Telegram
VIBER	Viber Business Messages
VIBERBOTS	Viber Bots
WHATSAPP	WhatsApp
ZALONS	Zalo Notification Service
APPLECB	Apple Messages for Business

Traffic types

In messaging platforms like WhatsApp and RCS, trafficTypes classify messaging interactions based on their purpose and nature. This structured classification provides valuable insights into communication patterns and helps analyze messaging behavior.

Traffic types overview - WhatsApp

Traffic types include the following categories:

Marketing: Promotional messages aimed at customer engagement.
Utility: Transactional messages providing essential updates, such as order confirmations.
Authentication: Messages used for identity verification, such as one-time passwords (OTPs).
Service conversations: Customer service interactions, typically initiated by the customer.

Traffic types overview - RCS

Traffic types are categorized as:

Basic transactions: Simple message exchanges, such as notifications.
Single transactions: One-off interactions between users and businesses.
A2P conversations: Application-to-person messaging, often used for promotional or transactional purposes.
P2A conversations: Person-to-application messaging, typically initiated by end users.

Key metrics for message analysis

INTERACTION_COUNT
- Represents the number of distinct sessions or conversations. This metric provides a detailed view of messaging traffic by capturing the volume of conversations or sessions.
  - When combined with the TRAFFIC_TYPE dimension, INTERACTION_COUNT helps categorize interactions into specific WhatsApp or RCS categories, such as conversations or sessions.

DELIVERED_TRAFFIC_COUNT
- Tracks the number of individual messages delivered.
  - This metric, when used with the TRAFFIC_TYPE dimension, is ideal for analyzing individual messages (RSC single and basic transactions), offering granular insights into message delivery performance.

By utilizing these metrics and dimensions, businesses can gain actionable insights into their messaging operations, enabling them to better understand and optimize their communication strategies.

ID	Name	Description
1	`UTILITY_CONVERSATION`	WA Utility conversation
2	`AUTHENTICATION_CONVERSATION`	WA Authentication conversation
3	`MARKETING_CONVERSATION`	WA Marketing conversation
4	`SERVICE_CONVERSATION`	WA Service conversation
5	`BASIC_TRANSACTION_BASED_MESSAGE`	RCS basic transaction based message
6	`SINGLE_TRANSACTION_BASED_MESSAGE`	RCS single transaction based message
7	`A2P_CONVERSATION`	RCS A2P (Application-to-Person) conversation
8	`P2A_CONVERSATION`	RCS P2A (Person-to-Application) conversation

Sender types

The table below outlines various sender types (senderTypes) available for messaging operations, each serving specific purposes and catering to different regions.

ID	Name	Description
1	`ALPHANUMERIC`	Alphanumeric sender
2	`SHORT_CODE`	Short numbers
3	`TOLL_FREE_NUMBER`	Toll free number (Limited to North America)
4	`VIRTUAL_LONG_NUMBER`	Virtual long number
5	`10DLC`	10DLC (Limited to North America)
6	`DOMAIN`	Used for Email

Sender types for some channels like Viber BM or RCS are mapped to their channel value, as specific sender types are not relevant to them.

Querying data Examples