View Campaigns Delivery report

Copied

                https://api.ocamba.com/v1/hood/reports/campaigns/delivery

Campaigns Delivery report enables analysis of critical parameters and essential information

Rate limits:

Burst: 10/s
Steady: 150/m

query Parameters

Name

Description

sortstring

Sorts the response by specified field(s) with the option to specify sorting order (ascending by default, add prefix "-" for descending).

Examples:
GET /VERSION/hood/RESOURCE_NAME?sort=name → sorts per name, ascending
GET /VERSION/hood/RESOURCE_NAME?sort=-id → sorts per id descending
GET /VERSION/hood/RESOURCE_NAME?sort=id,-name → sorts per id ascending, then name descending

See tips for the list of sortable fields.

Example: sort=-field1,field2

pagestring

The page number indicates which set of items will be returned in the response. The format of request is "page=N,M" where 'N' (required) represents page number and 'M' (optional) is number of items per page.

Examples:
N=1, M=20 → returns page 1 with 20 items
N=2, M=20 → returns page 2 with 20 items (items 21-40)
N=3 → returns page 3. The number of objects returned depends on the resource settings.

Example: page=1,10

outstring

Data format output - 'csv' (default) or 'json'.

Example: out=json

resolutionstring

Data resoulution, supported values 'hour', 'day'.

Example: resolution=hour

fieldsstringrequired

Fields is array of dimensions and measures. You can use dimensions to categorize, segment, and reveal the details in your data. Measures contain numeric, quantitative values that you can measure. At least one measure is required.

Response status codes

200 - OK

Name

Description

ab_test_idinteger

Dimension
A unique identifier for the A/B test or multivariate experiment associated with the campaign. This links all related message variations under a single test group for accurate grouping, evaluation, and reporting.

Example: 1002

ab_test_namestring

Dimension
A descriptive name for the A/B test or experiment (e.g., "Spring Launch Subject Line Test"). Helps users recognize the purpose of the test and interpret results more easily across reporting tools and dashboards.

Example: Spring Launch Subject Line Test

campaign_idinteger

Dimension
Unique identifier for the campaign (e.g., "1002600"). In HoodEngage, a campaign is a fundamental entity that orchestrates audience targeting, creative templates (push, SMS, email, etc.), scheduling rules, and delivery parameters. This ID ties all performance data and analytics back to a specific campaign.

Example: 1002600

campaign_namestring

Dimension
Human-readable name of the campaign (e.g., "Chrismats Sale - Special discount"). Helps users easily identify and manage distinct campaigns within HoodEngage.

Example: Blackfriday Worldwide

channel_typestring

Dimension
The primary channel used for message delivery in HoodEngage. Possible values include:
- push: Push notifications (web or app)
- adex_push: Push notifications routed through Ocamba Adex service
- sms: SMS messages
- email: Email messages

Example: push

Possible values: push | adex_push | sms | email

churnfloat

Measure
The churn rate, expressed as a percentage (e.g., 5.0 means 5%). It represents the proportion of users who unsubscribed during the campaign’s delivery, calculated relative to the total targeted users.

Example: 1.5

click_ratefloat

Measure
Percentage of delivered messages where at least one link was clicked by the recipient. Applies to channels that support click tracking (e.g., email, push, sms). Calculated as `(clicks / delivered) * 100`.

Example: 12.34

container_idinteger

Dimension
Unique identifier assigned by the HoodEngage app for a container resource. A container is an editable resource that centralizes settings for push notifications, analytics, crash reporting, user consent, and various lead-generation features (e.g., newsletter or SMS pop-ups). These changes are applied upon the next user session or SDK run.

Example: 126598752

container_namestring

Dimension
The name given by the user when creating a container.

Example: BBC Network US

deal_idstring

Dimension
A unique identifier for the HoodEngage deal associated with campaign (e.g., "1000251"). A deal represents the commercial arrangement or contractual terms under which the campaign operates—such as pricing models, frequency caps, billing rules, or postback configurations.

Example: 1000251

deal_namestring

Dimension
A descriptive name for the deal (e.g., "Nike landing page deal"), helping users understand the specific arrangement or financial terms linked to targeted campaign. This may reference shared business agreements, budgeting constraints, or frequency-limiting logic.

Example: Nike landing page deal

deliveredinteger

Measure
Total number of messages or notifications successfully delivered (sometimes referred to as "woken up", especially in the context of push). "Delivered" signifies how many end users actually received the campaign’s content.

Example: 888248

dsp_partner_idinteger

Dimension
The partner ID for the demand-side partner (DSP). Internally, this references the same partner_id field used by HoodEngage. However, we prefix it with “dsp_” to indicate the partner is acting as the advertiser, agency, or brand sponsoring campaigns to reach targeted audiences. Note that a single partner can function as both DSP and SSP, but this specific field is dedicated to identifying the partner in its demand-side role.

Example: 874214212

dsp_partner_namestring

Dimension
The name of the demand-side partner (e.g., "Nike Europe"). This partner is responsible for supplying the demand—i.e., advertising messages or brand content— in HoodEngage's ecosystem. Used in reporting and dashboards to identify the organization managing the campaign.

Example: Default partner

failedinteger

Measure
Total number of messages that failed to reach end users—for example, due to invalid contact information, unsubscribes, or provider-level blocks. This metric helps identify delivery issues for further troubleshooting.

Example: 9

impressioninteger

Measure
Total number of impressions served (particularly relevant for "adex_push"). HoodEngage records how many times the Adex campaign was visually displayed, separate from any auto-initiated notifications or background updates.

Example: 9

message_idinteger

Dimension
A unique identifier for a specific message variation used in a campaign—commonly part of an A/B or multivariate test. This ID enables detailed tracking, delivery, and performance analysis per message within a campaign.

Example: 1001

message_namestring

Dimension
A human-readable name for the message variation. Used in UIs and reports to help users understand the purpose or content of each test variant, especially in multi-message campaigns.

Example: variant A

open_ratefloat

Measure
Percentage of delivered emails that were opened at least once by recipients. Calculated as `(opens / delivered) * 100`. This metric applies only to the email channel and may be skewed by client-side privacy features.

Example: 55.56

openedinteger

Measure
Total number of unique times an email message was opened by a recipient. This is tracked via an invisible pixel embedded in the email and may be affected by email client privacy settings (e.g., Apple Mail Privacy Protection).

Example: 5

run_datedateTime

Dimension
The date/time for the event.
Resolution may be at the day or hour level:
- Day-level: "2025-03-04T00:00:00Z"
- Hour-level: "2025-03-04T07:00:00Z"

Example: 2025-03-04T07:00:00Z

sentinteger

Measure
Total number of messages that successfully reached the channel provider (e.g., FCM/APNs for push, SMS gateways like Twilio or Telesign, or email providers like Mailchimp or SendGrid). This does not guarantee end-user delivery, as failures can still occur after the provider accepts the message.

Example: 9

ssp_partner_idinteger

Dimension
The partner ID for the supply-side partner (SSP). Internally, this also references the same partner_id field used by HoodEngage. We prefix it with "ssp_" to indicate the partner is acting as the publisher, platform, or network that provides user traffic or a subscriber base. A single partner can fill both supply-side and demand-side roles, but this field specifically denotes the supply-side role for campaign distribution.

Example: 68745145

ssp_partner_namestring

Dimension
The name of the supply-side partner (e.g., "CNN East Europe"). This identifies the publisher or provider of traffic or user engagements in HoodEngage’s reporting.

Example: Default partner

total_clickinteger

Measure
Total number of all clicks resulting from targeted campaign. For push, includes clicks on the notification body or action buttons; for SMS or email, includes link clicks tracked by HoodEngage.

Example: 9

total_userinteger

Measure
The total number of users targeted by the campaign. HoodEngage calculates this by filtering users and deduplicating various user lists or targeting criteria before sending messages.

Example: 888248

unsubscribedinteger

Measure
The total count of users who unsubscribed immediately following targeted campaign. This is typically seen with channels such as email or SMS, which directly provide an "unsubscribe" or "opt-out" link tied to the campaign. (Push notifications often have different unsubscribing flows that are not always linked to a specific campaign.)

Example: 5

tip

1 Sortable fields are: run_date, container_id, container_name, campaign_id, campaign_name, deal_id, deal_name, ssp_partner_id, ssp_partner_name, dsp_partner_id, dsp_partner_name, channel_type, message_id, message_name, ab_test_id, ab_test_name, total_user, sent, delivered, unsubscribed, failed, impression, total_click, churn, opened, open_rate, click_rate.

2 Filterable fields are: run_date, container_id, container_name, campaign_id, campaign_name, deal_id, deal_name, ssp_partner_id, ssp_partner_name, dsp_partner_id, dsp_partner_name, channel_type, message_id, message_name, ab_test_id, ab_test_name, total_user, sent, delivered, unsubscribed, failed, impression, total_click, churn, opened, open_rate, click_rate.

3 API provided filling empty entry points in between first and last date/hour. You should set with_fill parameter to true, but just in case the date dimension is requested only. It is in relation with resolution. You should pass day or hour, which defines what type of breakdown you request, default setup displays daily breakdown.

4 To get data by the time in your local time zone, you should set tz query parameter to the specific time zone. See the list of valid time zones here -> https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List.

5 For easier search, Reports API gives you the possibility of using one of the following labels: today, yesterday, last-7-days, last-30-days, last-24-hours, this-month, last-month, current-hour, last-hour, last-48-hours, last-2-days, month-to-date, month-to-yesterday, quarter-to-date.

6 The metrics available for reporting vary depending on the channel type. Each channel has its own set of metrics that are tracked to monitor performance. Below is a breakdown of the metrics by channel type:
- push: total_user, sent, delivered, unsubscribed, failed, total_click, churn, click_rate
- adex: total_user, sent, delivered, failed, impression, total_click
- sms: total_user, sent, delivered, failed, total_click
- email: total_user, sent, delivered, failed, opened, open_rate
- email custom provider: total_user, sent
When querying the Campaigns Delivery Report, ensure you specify the appropriate channel to retrieve the corresponding metrics.

note

1 When filtering stat_date, use one of the following formats:
- Single format: YYYY-mm-dd;

Displaying stats for this specific day
- Range format: rf:YYYY-mm-dd,YYYY-mm-dd;
Requires usage of the range operators:
- r - range - The value must be in a specified open range, where both endpoints are excluded.
- rf - range full - The value must be in a specified closed range, where both endpoints are included.
- rl - range left - The value must be in a specified half-open range, where only left or start point is included.
- rr - range right - The value must be in a specified half-open range, where only right or end point is included.

Displaying stats in this specific range.
- Hour range format: rl: YYYY-mm-dd hh:00:00,YYYY-mm-dd hh:00:00
If you exclude this parameter, the default setup displays "today" stats.

Response examples

Copied

200

[
    {
      {
        "container_name": "Example container",
        "campaign_id": "1000123",
        "campaign_name": "Campaign - Example",
        "run_date": "2024-11-14T12:45:00Z",
        "deal_id": "100011",
        "deal_name": "deal cycle",
        "ssp_partner_id": "1234567",
        "ssp_partner_name": "Ocamba",
        "dsp_partner_id": "1000499",
        "dsp_partner_name": "partner cycle",
        "channel_type": "email",
        "total_user": 1,
        "sent": 0,
        "delivered": 0,
        "failed": 1,
        "total_click": 0,
        "churn": 0
      },
      {
        "container_name": "Example container",
        "campaign_id": "1000123",
        "campaign_name": "Campaign - Example",
        "run_date": "2024-11-14T12:05:00Z",
        "deal_id": "1000557",
        "deal_name": "deal cycle",
        "ssp_partner_id": "1234567",
        "ssp_partner_name": "Ocamba",
        "dsp_partner_id": "1000499",
        "dsp_partner_name": "partner cycle",
        "channel_type": "adex_push",
        "total_user": 1,
        "sent": 1,
        "delivered": 5,
        "failed": 0,
        "total_click": 4,
        "churn": 0
      }
    }
]

{
  "run_date": "2025-03-04T07:00:00Z",
  "container_id": 126598752,
  "container_name": "BBC Network US",
  "campaign_id": 1002600,
  "campaign_name": "Blackfriday Worldwide",
  "deal_id": "1000251",
  "deal_name": "Nike landing page deal",
  "dsp_partner_id": 874214212,
  "dsp_partner_name": "Default partner",
  "ssp_partner_id": 68745145,
  "ssp_partner_name": "Default partner",
  "channel_type": "push",
  "message_id": 1001,
  "message_name": "variant A",
  "ab_test_id": 1002,
  "ab_test_name": "Spring Launch Subject Line Test",
  "total_user": 888248,
  "delivered": 888248,
  "sent": 9,
  "failed": 9,
  "unsubscribed": 5,
  "churn": 1.5,
  "total_click": 9,
  "impression": 9,
  "opened": 5,
  "open_rate": 55.56,
  "click_rate": 12.34
}

View Campaigns Delivery report

GET /reports/campaigns/deliveryCopied https://api.ocamba.com/v1/hood/reports/campaigns/delivery

GET /reports/campaigns/delivery
Copied
`https://api.ocamba.com/v1/hood/reports/campaigns/delivery`