---
title: "POST /email-rules"
method: POST
path: "/email-rules"
---

# POST /email-rules

`POST /email-rules`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/email-rules`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Request body

- object: Request body for creating an email allow/block rule
  - `direction` 'SEND' | 'RECEIVE', required: SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented.
  - `action` 'ALLOW' | 'BLOCK', required: BLOCK refuses the matching address. ALLOW does two things: it carves an exception out of a broader BLOCK, AND it switches that scope+direction into allow-list mode — once any ALLOW rule exists, addresses it does not cover are refused. Adding one ALLOW rule therefore restricts far more than it permits.
  - `patternType` 'ADDRESS' | 'DOMAIN', required: ADDRESS matches one exact address. DOMAIN matches the domain and its subdomains ('example.com' covers 'a@mail.example.com' but never 'a@notexample.com'). ADDRESS beats DOMAIN when both match.
  - `pattern` string, required: The address or domain this rule matches. Normalized to lowercase. Validated against patternType.
  - `agentId` string, nullable: Scope the rule to one agent. Omit or null for an org-wide rule. An agent's own rules take precedence over org-wide rules — including its allow-list, which does NOT inherit the org's.
  - `note` string, nullable: Optional operator note ('known phisher', 'competitor'). Surfaced in the error a blocked send returns and in the security event, so a refusal is diagnosable without opening the console.

## Response `200`

OK

- object: An email allow/block rule
  - `id` string, required: Unique identifier of the rule
  - `direction` 'SEND' | 'RECEIVE', required: SEND governs who this org's agents may email (enforced when a send is attempted); RECEIVE governs whose mail is accepted for them (enforced at ingest, before the message is stored or any webhook fires). Reply-scope is not implemented.
  - `action` 'ALLOW' | 'BLOCK', required: BLOCK refuses the matching address. ALLOW does two things: it carves an exception out of a broader BLOCK, AND it switches that scope+direction into allow-list mode — once any ALLOW rule exists, addresses it does not cover are refused. Adding one ALLOW rule therefore restricts far more than it permits.
  - `patternType` 'ADDRESS' | 'DOMAIN', required: ADDRESS matches one exact address. DOMAIN matches the domain and its subdomains ('example.com' covers 'a@mail.example.com' but never 'a@notexample.com'). ADDRESS beats DOMAIN when both match.
  - `pattern` string, required: The normalized (lowercase) address or domain this rule matches
  - `agentId` string, nullable, required: The agent this rule is scoped to, or null for an org-wide rule
  - `note` string, nullable, required: Operator note, or null if not set
  - `createdAt` string, date-time, required: Timestamp when the rule was created
  - `updatedAt` string, date-time, required: Timestamp when the rule was last modified

---

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