---
title: "List receive rules"
canonical: "https://bird.com/docs/api/reference/list-mailbox-receive-rules"
---

# List receive rules

`GET /v1/email/mailboxes/{mailbox_id}/receive-rules`

Returns a paginated list of the mailbox's receive rules, oldest first. Filter by action to see only allow or only block entries.

## Code samples

**TypeScript**

```ts
for await (const rule of bird.email.mailboxes.receiveRules.list("mbx_01abc")) {
  console.log(rule.action, rule.entry);
}
```

Examples: [TypeScript](/docs/api/reference/list-mailbox-receive-rules.ts.md) · [Python](/docs/api/reference/list-mailbox-receive-rules.py.md) · [Go](/docs/api/reference/list-mailbox-receive-rules.go.md) · [PHP](/docs/api/reference/list-mailbox-receive-rules.php.md) · [CLI](/docs/api/reference/list-mailbox-receive-rules.cli.md) · [MCP](/docs/api/reference/list-mailbox-receive-rules.mcp.md) · [cURL](/docs/api/reference/list-mailbox-receive-rules.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "erl_01krdgeqcxet5s7t44vh8rt9mg",
      "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
      "action": "allow",
      "entry": "partner.example.com",
      "entry_type": "address"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Path parameters

- `mailbox_id` (string): Mailbox identifier. Starts with `mbx_`.

## Query parameters

- `action` (string)

  Return only `allow` or `block` rules; omit to return both actions.

  Possible values: `allow`, `block`
- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

## Response body

- `data` (array of object, required)
- `data.id` (string, required): Identifies this rule for deletion. There is no update operation.
- `data.mailbox_id` (string, required): The mailbox the rule applies to.
- `data.action` (string, required)

  What the rule does when it matches. Block rules always win: over allow rules and over the reply admission on allowlist mailboxes.

  Possible values: `allow`, `block`
- `data.entry` (string, required): The sender address or domain the rule matches. Domains also match their subdomains.
- `data.entry_type` (string, required)

  Whether the entry is a full address or a domain.

  Possible values: `address`, `domain`
- `data.note` (nullable string, required): Your own note about why the rule exists. `null` when unset.
- `data.created_at` (string, required): When the rule was created.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)