---
title: "Replace lists"
method: PUT
path: "/mailboxes/{address}/lists"
tags: ["Lists"]
---

# Replace lists

`PUT /mailboxes/{address}/lists`

## Request

- Base URL: `https://faivelo.com/api/v1`
- URL: `https://faivelo.com/api/v1/mailboxes/{address}/lists`
- Auth: HTTP bearer

Makes each list named in the body exactly the entries given. Lists not named are left as they are; an empty array clears a list. Requires scope `mailboxes:write` on an **account** key: agent keys, OAuth connections and single-mailbox keys can read the lists but not change them, so software cannot loosen its own guardrail.

## Path parameters

- `address` string, required

## Request body

- MailboxListsChange: Name one or more of the four lists. Up to 500 entries per list.
  - `send` object
    - `allow` string[]: Addresses or domains. Once this has any entry, only what it names gets through.
    - `block` string[]: Addresses or domains that are always turned away
  - `receive` object
    - `allow` string[]: Addresses or domains. Once this has any entry, only what it names gets through.
    - `block` string[]: Addresses or domains that are always turned away

## Response `200`

All four lists as they stand now

- object
  - `success` boolean
  - `data` MailboxLists
    - `send` object: Who this mailbox may send to through the API and MCP
      - `allow` string[]: Addresses or domains. Once this has any entry, only what it names gets through.
      - `block` string[]: Addresses or domains that are always turned away
    - `receive` object: Whose mail reaches this mailbox's inbox
      - `allow` string[]: Addresses or domains. Once this has any entry, only what it names gets through.
      - `block` string[]: Addresses or domains that are always turned away

## Other responses

- `401`: Missing or invalid API key
- `402`: The account's plan does not include the API (`plan_required`)
- `403`: The key lacks the required scope
- `404`: Resource not found
- `409`: The mailbox runs its own mail filter script, so receive lists cannot be applied
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/faivelo/apis/faivelo-api.md) · [All operations](https://skmtc.dev/faivelo/apis/faivelo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faivelo/apis/faivelo-api/revisions/a7413ddea5d1?raw)