Read the email allowance of a site

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.

POST /v1/get_site_email_usageScopeconfig:readRead only

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.

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.

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.

Inputs

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

Response

Every call answers with the JSON envelope 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 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 explains every status code a call can answer with.