---
title: "Add an email-domain rule"
method: POST
path: "/stats/email-domains"
tags: ["Stats"]
---

# Add an email-domain rule

`POST /stats/email-domains`

## Request

- Base URL: `https://api.nippy.host`
- URL: `https://api.nippy.host/stats/email-domains`
- Auth: `bearer` (a scheme the document does not define)

Admin-only. Adds a `block` or `allow` rule. Applies to new signups and address changes at once; existing users keep their sign-in. Records `email_domain.added`.

## Request body

- AddEmailDomainRuleDto
  - `domain` string, required: Domain to match, e.g. `example.com`. A leading `@` or `*.` and a trailing dot are ignored. The rule also covers every subdomain.
  - `kind` 'block' | 'allow', required: `block` refuses new signups on the domain; `allow` exempts it from every block, including the community list.
  - `note` string: Why the rule exists — typically the incident behind it.

## Response `201`

- APIEmailDomainRule
  - `id` string, required: Rule id (UUID).
  - `domain` string, required: The domain; the rule also covers subdomains.
  - `kind` 'block' | 'allow', required
  - `note` string, nullable, required
  - `createdByName` string, nullable, required: Display name of the admin who added the rule; null for seeded rules or a deleted admin.
  - `createdAt` string, required: When the rule was added (ISO 8601).
  - `existingUsers` number, required: Existing users with an address on the domain or a subdomain. They keep their sign-in: rules only apply to new addresses.

## Other responses

- `400`: Malformed domain, or a block on a major mailbox provider
- `403`: Admin access required
- `409`: A rule for the domain already exists

---

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