---
title: "Transactional email quota and usage: recipients today (UTC), this billing period and in the rolling hour. Any member with email:read"
method: GET
path: "/email/usage"
tags: ["Email"]
---

# Transactional email quota and usage: recipients today (UTC), this billing period and in the rolling hour. Any member with email:read

`GET /email/usage`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/email/usage`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Query parameters

- `orgId` string: Organization id (required when you belong to several)

## Response `200`

Quota and usage

- object
  - `organizationId` string, uuid, required
  - `sendingStatus` 'not_requested' | 'requested' | 'enabled' | 'suspended', required
  - `planId` string, nullable, required: the plan the quota comes from (free, pro, business); null for a team without plan limits
  - `source` 'plan' | 'override' | 'unlimited', required: override: a platform operator set this team's daily and/or monthly amount
  - `day` object, required
    - `used` integer, required: recipients (to + cc + bcc) of accepted sends through POST /emails in this window, plus the SMTP messages the mail server last reported (smtpCounted)
    - `limit` integer, nullable, required: null = no quota
    - `remaining` integer, nullable, required: limit - used, never below 0; null = no quota
    - `resetsAt` string, required: next 00:00 UTC
  - `month` object, required
    - `used` integer, required: recipients (to + cc + bcc) of accepted sends through POST /emails in this window, plus the SMTP messages the mail server last reported (smtpCounted)
    - `limit` integer, nullable, required: null = no quota
    - `remaining` integer, nullable, required: limit - used, never below 0; null = no quota
    - `periodStart` string, required: ISO-8601 timestamp
    - `resetsAt` string, required: end of the billing period (the calendar month in UTC without a subscription)
  - `hour` object, required: the burst guard: a quarter of the daily quota per rolling 60 minutes, counted like the mail server counts it (from the start of the minute 60 minutes ago)
    - `used` integer, required: recipients (to + cc + bcc) of accepted sends through POST /emails in this window, plus the SMTP messages the mail server last reported (smtpCounted)
    - `limit` integer, nullable, required: null = no quota
    - `remaining` integer, nullable, required: limit - used, never below 0; null = no quota
    - `resetsAt` string, nullable, required: when the oldest API send of the rolling hour leaves it; null when no API send is in the hour
  - `paused` object, nullable, required: a quota is used up until this moment: POST /emails answers rate_limited, and SMTP messages sent meanwhile are held by the mail server and not delivered
    - `window` 'day' | 'month', required
    - `until` string, required: ISO-8601 timestamp
  - `smtpCounted` boolean, required: true: SMTP relay is counted too, as the mail server reported it at smtpCountedAt (read about once a minute); false: the mail server cannot report it on this server yet, so only POST /emails is counted (and SMTP passwords are only issued to teams without a quota)
  - `smtpCountedAt` string, nullable, required: when the SMTP counts were last read from the mail server; null = never
  - `upgradeAvailable` boolean, required: a bigger plan with a higher quota can be bought on this server (Settings → Billing)

## Other responses

- `400`: Invalid request (code invalid_request)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Conflicting state (code conflict)
- `429`: Too many requests (code rate_limited); see Retry-After
- `501`: Not available on this server (code not_configured)
- `503`: Mail server or sending service unavailable (code provider_unavailable)

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)