---
title: "Create an email security rule"
method: POST
path: "/v2/email-security/settings/rules"
tags: ["Email Security"]
---

# Create an email security rule

`POST /v2/email-security/settings/rules`

## Request

- Base URL: `https://api.adaptivesecurity.com`
- URL: `https://api.adaptivesecurity.com/v2/email-security/settings/rules`
- Auth: HTTP bearer

Creates one enabled allow-list or deny-list rule. Requires EMAIL_SECURITY_WRITE. DMI_HEADER rules require header conditions and the ALLOW list. Deny and IP rules always use NONE authentication; DMI_HEADER uses AUTHENTICATED. Domain and email allow rules preserve the requested authentication requirement. IP ranges are canonicalized. Existing rules on either list cause a conflict. Returns the same rule representation as the list endpoint. Fields use snake_case.

**Required permission:** `email_security:write`

## Request body

- CreateEmailSenderRuleRequestDto: A new allow-list or deny-list rule
  - `auth_requirement` 'AUTHENTICATED' | 'NONE', required: Sender authentication requirement. list_type 'DENY' rules are always NONE, rule_type DMI_HEADER is always AUTHENTICATED
  - `header_rules` HeaderRulesRequestDto, required: Header conditions for the new rule
    - `operator` 'AND' | 'OR', nullable: How to combine conditions; defaults to AND
    - `rules` HeaderMatchRuleDto[], required: Non-empty list of header conditions
      - `header` string, required: Header name
      - `value` string, required: Value or regular expression to match
      - `value_type` 'STATIC' | 'REGEX' | 'CONTAINS' | 'STARTS_WITH', required: How to match the value
  - `list_type` 'ALLOW' | 'DENY', required: Allow or deny matching mail
  - `name` string: Display name for the rule
  - `rule_type` 'DMI_HEADER' | 'DOMAIN' | 'EMAIL' | 'IP' | 'IP_RANGE', required: Kind of sender match
  - `value` string, required: Value to match; ignored for DMI_HEADER

## Response `200`

Rule created

- EmailSenderRuleDto: Email security sender rule
  - `auth_requirement` 'AUTHENTICATED' | 'NONE', required: Sender authentication requirement
  - `created` string, date-time, required: Creation time
  - `header_rules` HeaderMatchRuleSetDto, required: Header conditions attached to a sender rule
    - `operator` 'AND' | 'OR', required: How to combine conditions; always AND for one condition
    - `rules` HeaderMatchRuleDto[], required: Header conditions
      - `header` string, required: Header name
      - `value` string, required: Value or regular expression to match
      - `value_type` 'STATIC' | 'REGEX' | 'CONTAINS' | 'STARTS_WITH', required: How to match the value
  - `id` string, uuid, required: Rule identifier
  - `list_type` 'ALLOW' | 'DENY', required: Whether the rule allows or denies matching mail
  - `name` string, required: Display name
  - `rule_type` 'DMI_HEADER' | 'DOMAIN' | 'EMAIL' | 'IP' | 'IP_RANGE', required: Kind of sender match
  - `updated` string, date-time, required: Last update time
  - `value` string, required: Value matched by the rule

## Other responses

- `400`: Invalid request body or rule value
- `401`: Invalid or missing authentication token
- `403`: Missing write permission or Email Security is not enabled
- `409`: A matching rule already exists on either list
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-19** `41f0ca9c551a`: 4 breaking, 2 warning, 1 info
  - the request property `header_rules` became not nullable
  - added `#/components/schemas/HeaderMatchRuleSetDto, subschema #2` to the `header_rules` response property `oneOf` list for the response status `200`
  - removed the required property `header_rules/operator` from the response with the `200` status
  - removed the required property `header_rules/rules` from the response with the `200` status
  - …3 more
- **2026-10-09** `1e527b1a2d31`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adaptivesecurity/apis/adaptive-api/changes/v2/email-security/settings/rules/post.md)

---

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