Usage · Email Marketing · API reference

GET/v1/email-marketing/usage

Get this month's email plan usage

email_marketing.usage.get

ReadIdempotentSince 2026-11-01

Returns the email marketing plan (5K, 10K or 25K) and this month's usage: sent (emails to contacts from campaigns and flows), limit (null when the organization has no cap), queued (emails waiting in the send queue, which also count), remaining (null without cap), overage (only the 25K plan allows going over; it is billed), usage_percent, a pending plan change and sending_paused (paused true when MB Suite paused the account's email sending, with kind and since: nothing goes out until it is resumed). Check remaining and sending_paused before sending a large campaign: email_marketing.campaigns.send_now refuses with limit_reached (details.resource emails) when the plan has no room and with email_sending_paused while sending is paused. Requires view access to Email Marketing.

Scope: email_marketing:read
Permission: View the module
MCP tool: email_marketing_usage_getOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.usage.get".

Declared cost: up to 3 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.

Response

plan_idstring | null

plan_namestring

sentnumber

limitnumber | null

Emails per month of the plan; null when there is no cap (unlimited true).

unlimitedboolean

true when the organization has no monthly cap (limit and remaining are null).

queuednumber

Emails in the queue that have not gone out yet (they count against the cap).

remainingnumber | null

What is left this month counting the queue; null without a cap.

overagenumber

overage_reportednumber

overage_cost_centsnumber

The overage's cost so far, in US cents.

usage_percentnumber

period_startnumber

Start of the month counted (epoch ms).

period_endnumber

End of the month counted (epoch ms).

pending_plan_changestring | null

allow_overageboolean

sending_pausedobject

Whether MB Suite paused the account's email sending (kind bounce_rate: a campaign or flow had a hard bounce rate over 5%; manual: MB Suite decided it; since: epoch ms). While paused nothing goes out, whatever the plan has left.

Errors

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

curl "https://api.mb-suite.com/v1/email-marketing/usage" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/email-marketing/usage" \
  -H "Authorization: Bearer $MB_TEST_KEY"