# get_site_email_usage

Source: https://modulify.ai/docs/api/emails/get-site-email-usage

Reads this calendar month's email usage of a site on its own, with the sends used, included and left and when the count resets.

- Title: Read the email allowance of a site
- Scope: `config:read`
- Access: Read only
- Endpoint: `POST /v1/get_site_email_usage`

It is the same usage `get_site_email_settings` carries, without the settings, so it answers how much sending the site has left. `usage` holds the sends used (`sent`), the sends included (`included`), how many extra blocks have been charged for (`overageBlocks`), the sends bought this month (`purchased`) and the ones bought in an earlier month and not used yet (`carriedOver`), what one block costs in credits (`blockCredits`), how many are left (`remaining`) and when the count resets (`resetsAt`). `limits` holds the per message limits.

Every recipient counts as one send, so one message to five people uses five. Test emails are free and never appear in it. The count is per site and starts again at zero at the beginning of each calendar month, in UTC. Unused included sends do not carry over, but bought sends left unused do, until they are used, and after a downgrade the higher included allowance stays until the month ends.

Free includes 50 sends per site a month, Starter 10,000, Pro 30,000 and Enterprise 50,000. Past that a paid plan keeps sending, and every further block of 2,000 sends costs 8 credits on Starter and Enterprise and 4 on Pro, taken automatically from the workspace the moment a send crosses the line. `blockCredits` carries the exact number of credits for this site. Free cannot buy blocks and stops at its limit.

While sending is paused because the workspace has no credits for the next block (`no-credits`) or a free site used everything (`plan-limit`), `usage.paused` carries that `reason`, `since` and `refused`, the number of sends refused so far. It clears on its own with the next send that goes through, once credits are added or the month resets.

It only reports. It cannot raise the allowance or buy a block, because a block is only ever charged by a send that needs it. Every block a site bought, with its credits and date, is listed by `list_workspace_credit_activity` with `category` set to `emails` and the site's `projectId`. See [Limits](https://modulify.ai/docs/automations/emails#limits).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/get_site_email_usage`, sending the inputs below as a JSON object. The token needs the `config:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/get_site_email_usage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'
```

Over MCP, the same method is the [get_site_email_usage tool](https://modulify.ai/docs/mcp/emails/get-site-email-usage).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.