API reference / Account

Get usage

Read the account's plan, inbox count, and remaining monthly balances. A 402 billing_limit error on another operation means a balance here is spent; upgrading is done by a person in the dashboard.

GET/v1/usage

Requires an API key with the inboxes:read scope. MCP tool: get_usage. CLI: goshenemail account usage.

Request

Response

Field	Type	Notes
`billing`	`"metered" \| "exempt" \| "disabled"`
`plan`	`object \| null`
`planId`	`string`
`status`	`string`
`currentPeriodEnd`	`string \| null`
`canceledAt`	`string \| null`
`inboxes`	`object`
`count`	`number`
`limit`	`number \| null`
`features`	`object[]`
`feature`	`string`
`granted`	`number \| null`
`used`	`number`
`remaining`	`number \| null`
`unlimited`	`boolean`
`resetsAt`	`string \| null`
`plans`	`object[]`
`planId`	`"free" \| "developer" \| "team"`
`name`	`string`
`description`	`string`
`price`	`number`
`included`	`object`
`inboxes`	`number`
`sends`	`number`
`triage`	`number`
`customDomains`	`number`
`storageMb`	`number`
`seats`	`number`
`topUps`	`boolean`

Errors return { "error": { "code", "message", "transient" } } with a 4xx or 5xx status. See Errors.

Examples

curl

curl "https://api.goshenemail.com/v1/usage" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY"

CLI

goshenemail account usage