> ## Documentation Index > Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk update mailboxes > Apply ONE settings/limits `patch` OR one `status` change (`active`/`inactive`) across many mailboxes. `patch` and `status` are mutually exclusive. Requires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`. ## OpenAPI ````yaml /openapi.json post /v1/accounts/bulk openapi: 3.0.0 info: title: MailBeast Public API description: >- Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key. version: '1' contact: {} servers: - url: https://api.mailbeast.ai security: [] tags: - name: API Keys description: Create, list and revoke API keys programmatically. - name: Campaigns description: Create, configure, launch and monitor email campaigns. - name: Leads description: Add, read, update and bulk-manage a campaign’s leads. - name: Workspace description: Read usage, subscription and workspace identity. - name: Email Accounts description: >- Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth). - name: Analytics description: Engagement reporting – per campaign, over time, and across the workspace. - name: Lead Finder description: >- Discover new companies and leads. List past searches and poll a running search’s progress. paths: /v1/accounts/bulk: post: tags: - Email Accounts summary: Bulk update mailboxes description: >- Apply ONE settings/limits `patch` OR one `status` change (`active`/`inactive`) across many mailboxes. `patch` and `status` are mutually exclusive. Requires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`. operationId: accounts_bulk parameters: - name: Idempotency-Key in: header description: >- Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`. required: false schema: type: string maxLength: 255 example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkAccountsApiDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BulkAccountsApiResponseDto' '400': description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: validation_failed message: One or more fields are invalid. status: 400 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f details: - name should not be empty '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authentication_error code: unauthenticated message: Missing or invalid API key. status: 401 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '403': description: >- The key lacks a required scope, or the plan does not include API access. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authorization_error code: permission_denied message: This API key is missing the required scope. status: 403 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '409': description: >- The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: conflict message: The request conflicts with an existing resource. status: 409 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '422': description: >- The Idempotency-Key was already used with a different request body. Use a new key for a new operation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: idempotency_key_reused message: >- The Idempotency-Key was already used with a different request body. Use a new key for a new operation. status: 422 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '429': description: >- Rate limit exceeded - retry after the interval in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval in the Retry-After header. status: 429 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f retryAfter: 30 security: - ApiKey: [] components: schemas: BulkAccountsApiDto: type: object properties: ids: maxItems: 1000 description: Target account ids. example: - 3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93 - 8c2f6a19-4b7d-4e53-91a0-5d3e7f6b2c84 type: array items: type: string status: type: string enum: - active - inactive description: >- Enable (`active`) or disable (`inactive`) sending across the set. Mutually exclusive with `patch`. patch: description: >- Settings/limits to apply to every account. Mutually exclusive with `status`. allOf: - $ref: '#/components/schemas/BulkAccountPatchApiDto' required: - ids BulkAccountsApiResponseDto: type: object properties: updated: type: number example: 5 description: Accounts updated. skipped: type: number example: 1 description: Mailboxes that were not eligible for this change. skippedAccounts: type: array items: $ref: '#/components/schemas/BulkSkippedAccountDto' required: - updated - skipped - skippedAccounts ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error BulkAccountPatchApiDto: type: object properties: displayName: type: string maxLength: 128 example: Jane Doe firstName: type: string example: Jane maxLength: 128 lastName: type: string example: Doe maxLength: 128 maxEmailsPerDay: type: number minimum: 1 maximum: 200 example: 60 replyToAddress: type: string maxLength: 254 example: replies@acme.com description: >- Pass `""` to clear it and reply to each mailbox address again, same as the single PATCH. sendingGapMinutes: type: number minimum: 1 maximum: 300 example: 10 campaignSlowRamp: type: boolean example: false signature: type: string example: Best regards,
Jane bcc: type: string maxLength: 254 example: archive@acme.com automationLanguage: type: string enum: - en - ar - bn - zh - cs - da - nl - fi - fr - de - el - he - hi - hu - id - it - ja - ko - ms - 'no' - pl - pt - ro - ru - es - sv - th - tr - uk - vi example: en tracking: $ref: '#/components/schemas/AccountTrackingApiDto' warmup: $ref: '#/components/schemas/AccountWarmupApiDto' BulkSkippedAccountDto: type: object properties: id: type: string format: uuid example: 3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93 description: >- The id you passed in `ids`, so a skip can always be matched back to the request. email: type: string nullable: true example: jane@acme.com description: >- Null when the id matches no mailbox in your workspace (`status: "not_found"`). status: type: string example: checking reason: type: string example: Account is being verified. required: - id - email - status - reason ApiErrorBodyDto: type: object properties: type: type: string example: authorization_error description: Broad error class. code: type: string example: permission_denied description: Stable machine-readable code to switch on. message: type: string example: This API key is missing the required scope. status: type: number example: 403 requestId: type: string example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f description: Correlation id - quote it in support requests. details: description: Field-level validation messages (present on validation errors). example: - name should not be empty type: array items: type: string retryAfter: type: number description: Seconds to wait before retrying (present on 429 responses). example: 30 required: - type - code - message - status - requestId AccountTrackingApiDto: type: object properties: domainId: type: string format: uuid example: 9b7d4e53-91a0-4c2f-8a19-5d3e7f6b2c84 nullable: true description: >- One of your workspace tracking domains. Attaching one enables open/click tracking for this mailbox. When omitted on connect, the workspace default is assigned; pass `null` for no tracking. AccountWarmupApiDto: type: object properties: enabled: type: boolean example: true description: Enroll the mailbox in warmup. Defaults to true on connect. strategy: type: string enum: - standard - aggressive - custom example: standard description: >- `standard` and `aggressive` are fixed profiles (conservative / faster) with their own ramp, cap and reply rate. `custom` is what makes `maxPerDay`, `rampupEnabled`, `dailyRampup`, `randomizer` and `replyRatePercentage` take effect. maxPerDay: type: number minimum: 0 maximum: 30 example: 15 description: >- Warmup emails per day, up to 30. Separate from `maxEmailsPerDay`, which caps CAMPAIGN sending only. `0` keeps warmup on but sends nothing. While the mailbox is still ramping up this is honoured on `custom` only (the preset strategies use their own cap), but once warmup reaches the steady maintaining stage it is the ceiling for EVERY strategy. replyRatePercentage: type: number minimum: 20 maximum: 80 example: 35 description: >- Share of warmup emails that get a reply. `custom` strategy only; the presets use their own reply rate. rampupEnabled: type: boolean example: true description: >- Grow the daily volume gradually (by `dailyRampup` each day) instead of sending `maxPerDay` from day one. `custom` strategy only. dailyRampup: type: number minimum: 1 maximum: 10 example: 1 description: >- Emails added per day while ramping up. Read only when `rampupEnabled` is **true**. With ramp-up off the mailbox sends a flat `maxPerDay` every day and this is ignored. `custom` strategy only. randomizer: type: number minimum: 0 maximum: 50 example: 0 description: >- Percent of warmup sends randomly skipped each day, so volume is not identical day to day. `custom` strategy only. skipWeekends: type: boolean example: false description: Skip Saturdays and Sundays. timezone: type: string example: Europe/London description: >- IANA timezone the warmup schedule runs in. Defaults to the workspace timezone. trackingEnabled: type: boolean example: true description: Track opens on warmup emails. securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [Update a mailbox](/api-reference/email-accounts/update-a-mailbox.md) - [Leads](/leads.md) - [Email Accounts](/accounts.md) - [Bulk mutate leads](/api-reference/leads/bulk-mutate-leads.md) - [Update a campaign](/api-reference/campaigns/update-a-campaign.md)