> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimo.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Statistics widget

> Each restaurant sees how its own emails perform, with a plain sending status; the same numbers are available to your backend

## What the restaurant sees

![The statistics widget of a new restaurant: period switch and the "sending limited" status line](https://mintcdn.com/minimo/9ObazzQQNYTDa_5r/images/embedded/widget-statistics.png?fit=max\&auto=format\&n=9ObazzQQNYTDa_5r\&q=85\&s=280a06e7ba0e0c3d3db2cf1780a9a931)

*Shown in Italian, for a restaurant in its first days that has not sent yet.*

For the last 7, 30 or 90 days (whole days in the restaurant's time zone, today included):

* a sending status in plain words: **All good**, **Sending limited** (a new restaurant in its start-up phase, with today's promotional limit and how much of it is used) or **Sending paused** (promotional emails on hold, automatic messages keep going). It never shows thresholds, reasons or anything about other restaurants;
* sent, delivered, opened, clicks, then not delivered (address does not exist / mailbox full or temporary), blocked before sending, marked as spam, unsubscribed, not sent;
* a chart of the emails sent per day (per week for 90 days), with the numbers as a table;
* automatic messages compared with campaigns, and the five most sent messages with their open and click rates.

## Mount it

Permission `stats` (in the default; add it yourself when you pass an explicit `permissions` list):

```html theme={null}
<div id="minimo-stats"></div>
<script src="https://api.minimo.it/public/v1/embed/widgets/widgets.js"></script>
<script>
  Minimo.mountWidget({ url: session.urls.stats, container: '#minimo-stats', minHeight: 900 });
</script>
```

Events: `ready` with `period` (7, 30 or 90) and `sent`, `error`, `resize`.

## The same numbers for your own charts

```bash theme={null}
curl "https://api.minimo.it/public/v1/tenants/restaurant_4812/stats?period=30d&tz=Europe/Rome" \
  -H "Authorization: Bearer YOUR_MINIMO_KEY"
```

Permission `widgets` or `events`. `period` is `7d`, `30d` (default) or `90d`; `tz` an IANA time zone (default UTC). The answer (cached up to 3 minutes):

```json theme={null}
{
  "data": {
    "tenant": "restaurant_4812",
    "period": {
      "days": 30,
      "from": "2026-10-09T22:00:00.000Z",
      "to": "2026-11-08T14:54:36.379Z",
      "timeZone": "Europe/Rome",
      "bucket": "day"
    },
    "totals": {
      "sent": 412,
      "delivered": 401,
      "opened": 203,
      "clicked": 38,
      "hardBounced": 7,
      "softBounced": 3,
      "blocked": 1,
      "complaints": 0,
      "unsubscribed": 4,
      "notSent": 2,
      "rates": { "delivered": 97.3, "opened": 50.6, "clicked": 9.5, "bounced": 2.4, "complaints": 0, "unsubscribed": 1 }
    },
    "automatic": { "sent": 320, "...": "same fields" },
    "campaigns": { "sent": 92, "...": "same fields" },
    "trend": [{ "date": "2026-10-10", "sent": 12, "opened": 6, "clicked": 1 }],
    "top": [
      {
        "templateId": 905,
        "name": "Booking confirmation",
        "kind": "automatic",
        "sent": 210,
        "rates": { "opened": 58, "clicked": 4.8 }
      }
    ],
    "status": { "state": "limited", "dailyCap": 200, "usedToday": 40, "remainingToday": 160 }
  }
}
```

| Field | Meaning |
| - | - |
| `sent` | Emails that left Minimo, including the ones that bounced afterwards. Emails still queued are not counted yet. |
| `notSent` | Emails refused before leaving (no consent, address suppressed, sending paused). |
| `delivered` | Sent and not bounced or blocked. |
| `opened` | Emails with a recorded open. An estimate: Apple Mail and some other apps open emails by themselves, so the real number can be lower. Clicks are more reliable. |
| `clicked` | Emails with at least one tracked click. |
| `hardBounced`, `softBounced` | The address does not exist / the mailbox was full or the problem was temporary. |
| `blocked` | Never attempted by the mail provider (the address is on its suppression list). Not counted as a bounce. |
| `complaints` | Recipients who marked the email as spam. |
| `unsubscribed` | Recipients who unsubscribed through one of these emails. |
| `rates` | Percentages with one decimal (`null` when there is nothing to divide by): `delivered`, `bounced` and `complaints` over sent; `opened`, `clicked` and `unsubscribed` over delivered. |
| `status.state` | `ok`, `limited` (with `dailyCap`, `usedToday`, `remainingToday` of promotional emails, UTC day) or `paused`. |

Errors: `400 INVALID_STATS_PERIOD`, `422 INVALID_TENANT`.

To bill your restaurants per email, count the messages per tenant with `GET /public/v1/messages/list?tenant=…` (see [Senders](https://docs.minimo.it/guides/embedded-senders-and-sending.md#3-tag-the-send-with-your-tenant)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.