---
title: "Create a receive rule"
canonical: "https://bird.com/docs/api/reference/create-mailbox-receive-rule"
---

# Create a receive rule

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

Adds an allow or block rule to the mailbox. Rules match the message's envelope sender. Domain entries also match subdomains. Block rules always win, both over allow rules and over the reply admission on allowlist mailboxes. An entry is either allow or block. Rules have no update operation, so a rule that needs the other action is a new rule and the old one is removed. A mailbox holds up to 200 rules.

## Code samples

**TypeScript**

```ts
const rule = await bird.email.mailboxes.receiveRules.create("mbx_01abc", {
  action: "block",
  entry: "spam.example.com",
});
console.log(rule.id);
```

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

## Example response `201`

```json
{
  "id": "erl_01krdgeqcxet5s7t44vh8rt9mg",
  "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
  "action": "allow",
  "entry": "partner.example.com",
  "entry_type": "address"
}
```

## Path parameters

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

## Request body

- `action` (string, required)

  What the rule does when it matches. Block rules always win. To flip an entry's action, delete the existing rule and re-create it.

  Possible values: `allow`, `block`
- `entry` (string, required): The sender address (`alice@example.com`) or domain (`example.com`) to match. Domains also match their subdomains. Stored lowercase.
- `note` (string): Your own note about why the rule exists.

## Response body

- `id` (string, required): Identifies this rule for deletion. There is no update operation.
- `mailbox_id` (string, required): The mailbox the rule applies to.
- `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`
- `entry` (string, required): The sender address or domain the rule matches. Domains also match their subdomains.
- `entry_type` (string, required)

  Whether the entry is a full address or a domain.

  Possible values: `address`, `domain`
- `note` (nullable string, required): Your own note about why the rule exists. `null` when unset.
- `created_at` (string, required): When the rule was created.

## 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)