MCP rate limits

MailSenpai MCP applies rate limits per connected user, customer and tool class. Each MCP tool call consumes one request in the matching class. Limits protect stability, database-heavy endpoints and high-impact actions; they are not the number of email recipients MailSenpai can deliver to.

In practice: creating a campaign, scheduling it and reading a report consume different classes. If a limit is exceeded the server returns HTTP 429 with Retry-After; the AI client should wait before retrying.

Class	Default limit	When it applies	Real example
`read` Read/search	60/min	Browsing existing MailSenpai data without changing it.	An assistant lists your campaigns, opens one campaign and checks whether a subscriber is already in a list. This normally consumes a few read calls.
`report` Reports/statistics	30/min	Campaign performance and analytics queries.	A weekly report comparing 10 campaigns can consume 10 report calls plus read calls for campaign metadata.
`write` General write	30/min	Non-sending changes such as contacts, fields, segments and templates.	Creating one segment and then adding three test contacts usually consumes four write calls.
`campaign` Campaign create/update	20/min	Campaign draft creation and campaign metadata/template changes.	A campaign workflow can create a template, create a campaign, update targeting and pause/resume it. Those campaign-specific steps consume campaign calls.
`bulk` Bulk/import/export	6/min	Large operations that process many records in one request.	Importing 500 subscribers in one allowed bulk request also remains subject to maxBulkImportRows, for example 500 or 1000 rows per request depending on plan.
`send` Send/schedule	10/min + 60/h	Operations that can place campaigns or transactional emails into a send path.	Scheduling three campaigns consumes three send calls and also counts against the hourly send/schedule ceiling.
`destructive` Delete/destructive	6/min	Deletes and other high-impact data removal actions.	Deleting five obsolete test campaigns consumes five destructive calls and also requires confirm_delete=true.
`admin` Admin/customer management	3/min	Rare administrative operations, normally disabled for ordinary customer plans.	An internal operator creating demo customers for review consumes admin calls and requires canManageCustomers.
`burst` Burst ceiling	3/sec	Short-term anti-spike protection applied before category-specific limits.	If an AI client retries too aggressively, the burst ceiling stops the spike and asks it to wait a few seconds.

Practical examples

Weekly performance summary

Calls: list_campaigns, get_campaign_stats x 10

{
  "read": 1,
  "report": 10
}

The assistant first finds campaigns, then reads statistics for each selected campaign.

Create a test segment and import contacts

Calls: create_list_segment, bulk_create_subscribers

{
  "write": 1,
  "bulk": 1
}

The bulk request is additionally limited by maxBulkImportRows.

Create and schedule one campaign

Calls: create_template, create_campaign, schedule_campaign_send

{
  "write": 1,
  "campaign": 1,
  "send": 1
}

Sending/scheduling still requires confirm_send and respects requiresApprovalForSend.

Clean up old test assets

Calls: delete_campaign x 3, delete_template x 2

{
  "destructive": 5
}

Destructive calls require confirm_delete and canDelete, even when rate-limit capacity is available.

Plan-configurable keys

These keys can be generated by the extension Policy Builder and stored in the group/customer limits_json.

{
  "read": "rateLimitReadPerMinute",
  "report": "rateLimitReportPerMinute",
  "write": "rateLimitWritePerMinute",
  "campaign": "rateLimitCampaignPerMinute",
  "bulk": "rateLimitBulkPerMinute",
  "send": "rateLimitSendPerMinute",
  "sendHour": "rateLimitSendPerHour",
  "destructive": "rateLimitDeletePerMinute",
  "admin": "rateLimitAdminPerMinute",
  "burst": "rateLimitBurstPerSecond"
}

Relationship with email sending

MCP rate limits restrict requests made by the AI assistant. Actual recipient delivery speed remains governed by MailSenpai, delivery servers, sender reputation, cron jobs and the commercial plan.