> ## Documentation Index > Fetch the complete documentation index at: https://docs.tawked.com/llms.txt > Use this file to discover all available pages before exploring further. # Get email metrics > The application's e-mail figures by Riyadh day, Sunday week or month, from the daily rollup Tawked keeps for good: sent, delivered, delayed, bounced (permanent and transient), complained, failed, suppressed, opened and clicked, with the rates. Counts are e-mails (recipients). Opens and clicks are counted in targets: a message sent to several people in one call counts as one target, since one pixel serves them all. Every period of the range is present, zeros included; the day in progress too, refreshed every five minutes. Test messages never count. A live key of the application with `email:read` (or `email:send`, or `email:manage`). Guide: [Metrics](https://docs.tawked.com/email/metrics.md) ## OpenAPI ````yaml https://tawked.com/openapi.json get /v1/email/metrics openapi: 3.1.0 info: title: Tawked API version: 2026-09 summary: >- Tawked Verify: OTP verification for Saudi mobile numbers over SMS, in two calls. Tawked Notifications: WhatsApp template messages from the application's own number. Tawked Email: transactional e-mail from the application's own verified domain. Tawked Chat: the conversation menus a connected app adds beside the conversations of its connection's application, and the auto-attendant it sets up there. The Partner API for platforms that run Tawked Verify for their merchants. description: >- The public API of Tawked, a Saudi messaging platform: Tawked Verify (one-time codes), Tawked Notifications (WhatsApp templates from the application's own number), Tawked Email (transactional e-mail from the application's own domain) and the Partner API. Tawked Verify is an OTP verification API for Saudi numbers. One call sends a one-time code by SMS to a Saudi mobile number, and a second call checks it. SAR 0.09 per SMS code sent, prepaid; a send the network refuses is refunded. Authenticate with a Bearer API key from the dashboard (tk_live_ for production, tk_test_ for the sandbox, tk_partner_ for partners, tk_partner_test_ for the partner sandbox). Partners (tk_partner_) provision a Verify application per merchant under /v1/partner/applications and name it as application on every Verify call. Both /v1/... and /api/v1/... answer identically. Rate limit: 120 requests per minute per key. termsOfService: https://tawked.com/en/terms license: name: Proprietary (Tawked terms of service) url: https://tawked.com/en/terms contact: name: Tawked support email: support@tawked.com url: https://tawked.com/en/contact servers: - url: https://tawked.com description: Production (the sandbox is a tk_test_ key on the same host) - url: https://tawked.com/api description: The same API under /api/v1/..., kept for older integrations security: - bearerKey: [] - headerKey: [] tags: - name: Verify x-group: Verify description: Send and check one-time codes. - name: WhatsApp x-group: Notifications description: >- Tawked Notifications: send approved WhatsApp templates through the number connected to an application. An application in review or approved connects its own number from the dashboard. - name: Email x-group: Email description: >- Tawked Email: send transactional e-mail from an address on a verified domain of the application, to up to 50 recipients a message, in batches or scheduled, and read and list what was sent. Live keys only. - name: Chat x-group: Chat description: >- Tawked Chat: the conversation menus a connected app adds beside the conversations of its connection's application, and reads, changes and removes, with `chat:menus`; and the application's auto-attendant, which a connected app sets up, publishes and switches on or off, with `chat:attendant`. A connected app's key only; a business adds its own menus and builds its auto-attendant in the console. - name: Partner x-group: Partner API description: >- For platforms that run Tawked Verify for their merchants: provision a Verify application per merchant, keep its brand and verify settings current, switch it off and on, and read usage and the code log. Partner keys (tk_partner_) only; every Verify operation then takes `application` with the partner's own id for the application. - name: Webhooks x-group: Webhooks description: >- The events Tawked sends to your endpoint: an application's verification outcomes and message statuses, and a partner account's lifecycle, balance and opt-in verification events. Every delivery is signed the same way and retried the same way. externalDocs: description: Developer docs, with code samples url: https://docs.tawked.com paths: /v1/email/metrics: get: tags: - Email summary: Get email metrics description: >- The application's e-mail figures by Riyadh day, Sunday week or month, from the daily rollup Tawked keeps for good: sent, delivered, delayed, bounced (permanent and transient), complained, failed, suppressed, opened and clicked, with the rates. Counts are e-mails (recipients). Opens and clicks are counted in targets: a message sent to several people in one call counts as one target, since one pixel serves them all. Every period of the range is present, zeros included; the day in progress too, refreshed every five minutes. Test messages never count. A live key of the application with `email:read` (or `email:send`, or `email:manage`). operationId: email_metrics parameters: - name: from in: query required: false description: The first Riyadh day, `YYYY-MM-DD`; 30 days before `to` by default. schema: type: string - name: to in: query required: false description: >- The last Riyadh day, `YYYY-MM-DD`; today by default. At most 366 days after `from`. schema: type: string - name: granularity in: query required: false description: '`day` (the default), `week` (weeks start on Sunday) or `month`.' schema: type: string - name: domain in: query required: false description: >- One domain of the application, by id or name (removed ones included). schema: type: string - name: timezone in: query required: false description: 'Only `Asia/Riyadh`: metrics are counted on Riyadh days.' schema: type: string responses: '200': description: The figures content: application/json: schema: type: object properties: from: type: string to: type: string timezone: type: string granularity: type: string domain: type: - string - 'null' totals: type: object properties: sent: type: integer delivered: type: integer delivery_delayed: type: integer bounced: type: integer bounced_permanent: type: integer bounced_transient: type: integer complained: type: integer failed: type: integer suppressed: type: integer opened: type: integer unique_opened: type: integer clicked: type: integer unique_clicked: type: integer open_tracked_targets: type: integer click_tracked_targets: type: integer rates: type: object properties: delivery_rate: type: number bounce_rate: type: number complaint_rate: type: number open_rate: type: number click_rate: type: number data: type: array items: type: object properties: period: type: string sent: type: integer delivered: type: integer delivery_delayed: type: integer bounced: type: integer bounced_permanent: type: integer bounced_transient: type: integer complained: type: integer failed: type: integer suppressed: type: integer opened: type: integer unique_opened: type: integer clicked: type: integer unique_clicked: type: integer open_tracked_targets: type: integer click_tracked_targets: type: integer examples: the_figures: summary: The figures value: from: '2026-10-01' to: '2026-10-20' timezone: Asia/Riyadh granularity: day domain: null totals: sent: 1200 delivered: 1180 delivery_delayed: 3 bounced: 12 bounced_permanent: 9 bounced_transient: 3 complained: 1 failed: 2 suppressed: 4 opened: 800 unique_opened: 510 clicked: 120 unique_clicked: 90 open_tracked_targets: 1100 click_tracked_targets: 1100 rates: delivery_rate: 0.9833 bounce_rate: 0.01 complaint_rate: 0.0008 open_rate: 0.4636 click_rate: 0.0818 data: - period: '2026-10-01' sent: 60 delivered: 59 delivery_delayed: 0 bounced: 1 bounced_permanent: 1 bounced_transient: 0 complained: 0 failed: 0 suppressed: 0 opened: 40 unique_opened: 26 clicked: 6 unique_clicked: 5 open_tracked_targets: 55 click_tracked_targets: 55 '400': description: >- Too long a range / `invalid_request`: start: `to` (and `phone`) both missing or blank. check: `id` or `code` missing. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - invalid_request examples: too_long_a_range: summary: Too long a range value: error: invalid_request message: The range is at most 366 days field: from '401': description: >- `unauthorized`: Missing, unknown, revoked, or mode-mismatched key; or an unknown/suspended partner.; `key_expired`: The key's `expires_at` has passed. Checked right after the key is recognised, before the IP allowlist or scope. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - unauthorized - key_expired '403': description: >- `live_key_required`: A test (tk_test_) key on a management endpoint: domains, suppressions, metrics and templates are the account's real objects, managed with the application's live key, and received e-mail is read with it too. A test key sends, reads and cancels messages in test mode; a partner's test key (tk_partner_test_) has no e-mail at all.; `application_key_required`: A partner key. Use the application's own key: partner keys manage client applications through the Partner API.; `account_not_active`: The application is not approved yet, the account is banned, or a partner disabled this application. All four causes share this one response.; `ip_not_allowed`: The caller's IP does not match the key's `ip_allowlist` (exact IPs and/or CIDR ranges, IPv4 and IPv6).; `insufficient_scope`: The key was not granted this call: a custom key without this product, or with a level below the call, such as a key that checks where the call sends. The response header `WWW-Authenticate` names the scope the call needs. Judged right after the key is recognised, before `account_not_active` and the request's shape. This operation needs `email:read`. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - live_key_required - application_key_required - account_not_active - ip_not_allowed - insufficient_scope headers: WWW-Authenticate: description: >- Sent with `insufficient_scope` only: the scope this operation needs, which the key was not granted. schema: type: string example: Bearer error="insufficient_scope", scope="email:read" '404': description: >- Not a domain of the application / `not_found`: An id that is not this application's: a message, a domain (a removed one too), a suppressed address, an import, a template or a version. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - not_found examples: not_a_domain_of_the_application: summary: Not a domain of the application value: error: not_found '409': description: >- `email_access_required`: The account has not asked for Email yet: ask from the application's Email area in the console.; `email_access_pending`: The account's request for Email waits for Tawked's team.; `email_product_off`: The application's Email product is off: turn it on in the console. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - email_access_required - email_access_pending - email_product_off '429': description: >- `too_many_requests`: Per-key rate limit exceeded (default 120 requests/minute, fixed 60s window; 1,200 on the e-mail endpoints). Checked before authentication. The `Retry-After` header gives the seconds to the next window. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - too_many_requests '500': description: >- `internal_error`: An unhandled server error. Quote the X-Request-Id header if you report it. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - properties: error: enum: - internal_error x-codeSamples: - lang: bash label: cURL source: >- curl "https://tawked.com/v1/email/metrics?from=2026-10-01&to=2026-10-20&granularity=day" \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxx" - lang: javascript label: Node.js source: >- const res = await fetch("https://tawked.com/v1/email/metrics?from=2026-10-01&to=2026-10-20&granularity=day", { headers: { Authorization: "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx", }, }); const data = await res.json(); - lang: python label: Python source: |- import requests res = requests.get( "https://tawked.com/v1/email/metrics?from=2026-10-01&to=2026-10-20&granularity=day", headers={"Authorization": "Bearer tk_live_xxxxxxxxxxxxxxxxxxxx"}, ) data = res.json() components: schemas: Error: type: object required: - error properties: error: type: string description: A stable machine-readable code; the docs list every one. additionalProperties: true securitySchemes: bearerKey: type: http scheme: bearer description: >- Authorization: Bearer . An application key (tk_live_, tk_test_) has full access, which covers every product and any product added later, or custom access, chosen when the key is created: one or more of the scopes `verify:check`, `verify:send` (includes `verify:check`), `notifications:read`, `notifications:send` (includes `notifications:read`), `email:read`, `email:send` (includes `email:read`), `email:manage` (includes `email:send`), `webhooks:manage`, `email:inbound`, `notifications:templates` (includes `notifications:read`), `chat:menus`, `chat:attendant`. No key made on the API keys page holds `notifications:templates`, full access included: the three template writes answer such a key 403 `insufficient_scope`. A connected app's key holds it. Nor `chat:menus`: the five conversation menu operations answer such a key 403 `insufficient_scope`, and a connected app's key holds it once the client approved it. Nor `chat:attendant`: the five auto-attendant operations answer such a key 403 `insufficient_scope` too, and a connected app's key holds it once the client approved it. `email:manage` and `webhooks:manage` are held only by a key someone chose them for: a full-access key, old or new, never holds them. `email:inbound`, which reads, deletes and forwards received e-mail, is opt-in on every key, full access included: a key holds it only when it was turned on when the key was created. A call outside the key's access answers 403 `insufficient_scope` and names the scope it needs in the `WWW-Authenticate` response header. A partner key (tk_partner_) always has full access. Whatever its access, a key is a server-side secret. headerKey: type: apiKey in: header name: x-api-key description: >- The same API key, with the same access, as a header, for clients that cannot set Authorization. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.