Sender Rules & Inbound Firewall API

Configure inbound email firewall rules to allowlist trusted senders or reject unwanted addresses, full domains, and wildcard patterns at the network edge.

Quick Reference

Endpoint	Method	Scope	Purpose
`/v1/sender-rules/whitelist`	`GET`	`sender_rules:read`	List configured allowed sender rules
`/v1/sender-rules/whitelist`	`POST`	`sender_rules:write`	Create an allowlist rule for an address, domain, or pattern
`/v1/sender-rules/whitelist`	`PATCH`	`sender_rules:write`	Toggle or update an allowlist rule
`/v1/sender-rules/whitelist`	`DELETE`	`sender_rules:write`	Delete an allowlist rule
`/v1/sender-rules/whitelist/stats`	`GET`	`sender_rules:read`	Retrieve allowlist volume and monthly trend metrics
`/v1/sender-rules/blacklist`	`GET`	`sender_rules:read`	List configured blocked sender rules
`/v1/sender-rules/blacklist`	`POST`	`sender_rules:write`	Create a denylist rule to reject senders or domains
`/v1/sender-rules/blacklist`	`PATCH`	`sender_rules:write`	Toggle or update a denylist rule
`/v1/sender-rules/blacklist`	`DELETE`	`sender_rules:write`	Delete a denylist rule
`/v1/sender-rules/blacklist/stats`	`GET`	`sender_rules:read`	Retrieve blocked volume and monthly trend metrics

Inbound Firewall Architecture

The AliasFleet Inbound Firewall evaluates incoming messages at the earliest possible stage of the email delivery pipeline:

Edge Rejection: When an inbound SMTP transaction arrives from a blocked sender or domain, the firewall terminates the session during the MAIL FROM envelope handshake with an RFC 5321 550 5.7.1 permanent failure code. The message body is never accepted or stored.
Mutual Exclusivity Invariant: A sender pattern cannot exist on both your allowlist and your denylist. If you attempt to allow an address that is currently blocked, the API rejects the request with CROSS_TABLE_CONFLICT.
Pattern Matching Hierarchy:
- Exact: Matches specific email addresses (spammer@example.com).
- Domain: Matches all senders under a domain (badcompany.com), with optional recursive subdomain coverage (includeSubdomains: true).
- Pattern: Advanced wildcard matching (*@promo.*.com, alert*@monitoring.internal).

GET /v1/sender-rules/whitelist — List Allowed Sender Rules

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns a paginated list of allowed sender rules configured for your workspace.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Number of records per page (max `100`).
`search`	`string`	Optional	—	Case-insensitive filter on `email_pattern`.
`includeGlobal`	`boolean`	Optional	`false`	When `true`, includes platform-wide system rules alongside workspace rules.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/whitelist?page=1&limit=2" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "entries": [
    {
      "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "user_id": "usr_9f8e7d6c5b4a3a2b",
      "email_pattern": "vip-notifications@partner.com",
      "pattern_type": "exact",
      "include_subdomains": false,
      "reason": "Critical billing and invoice updates",
      "source": "manual",
      "is_active": true,
      "allowed_count": 48,
      "created_at": "2026-08-20T10:00:00.000Z",
      "updated_at": "2026-08-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 1,
    "totalPages": 1
  }
}

POST /v1/sender-rules/whitelist — Create Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 30/min · Idempotent: Yes

Adds a sender address, domain, or wildcard pattern to your inbound allowlist.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`emailPattern`	`string`	Yes	1–255 chars	Email (`user@domain.com`), domain (`partner.com`), or wildcard pattern (`@.corp.com`).
`patternType`	`string`	Optional	`exact`, `domain`, `pattern`	Pattern evaluation strategy. Defaults to `exact`.
`includeSubdomains`	`boolean`	Optional	Boolean	When `true` with `patternType: "domain"`, matches subdomains (e.g. `*.partner.com`).
`reason`	`string`	Optional	Max 255 chars	Contextual note explaining why the sender is allowlisted.
`source`	`string`	Optional	Max 50 chars	Origin tag: `manual`, `quick_action`, or `api`. Defaults to `manual`.

Example Request

curl -X POST "https://api.aliasfleet.com/v1/sender-rules/whitelist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "emailPattern": "partner-network.com",
    "patternType": "domain",
    "includeSubdomains": true,
    "reason": "Authorized B2B syndication partner"
  }'

Response (`201 Created`)

{
  "success": true,
  "entry": {
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "partner-network.com",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Authorized B2B syndication partner",
    "source": "manual",
    "is_active": true,
    "allowed_count": 0,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:00:00.000Z"
  },
  "message": "partner-network.com has been added to the allowlist"
}

Errors

Status	Code	Cause & Resolution
`400 Bad Request`	`INVALID_PATTERN`	The `emailPattern` string is malformed or invalid syntax.
`402 Payment Required`	`ENTITLEMENT_REQUIRED`	Domain and wildcard rules require a Pro or Business plan.
`409 Conflict`	`CROSS_TABLE_CONFLICT`	The pattern already exists on your denylist (blacklist). Remove it from the denylist first.
`409 Conflict`	`ALREADY_EXISTS`	The pattern is already present on your allowlist.

PATCH /v1/sender-rules/whitelist — Update Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Toggles the active state or updates the description metadata for an existing allowlist rule.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`id`	`string`	Yes	Rule UUID	Unique identifier of the rule to modify.
`isActive`	`boolean`	Optional	Boolean	Activates or pauses rule enforcement.
`reason`	`string`	Optional	Max 255 chars	Updated note or rationale.
`includeSubdomains`	`boolean`	Optional	Boolean	Whether domain matching extends to subdomains.

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/sender-rules/whitelist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "isActive": false,
    "reason": "Temporarily disabled during vendor security audit"
  }'

Response (`200 OK`)

{
  "success": true,
  "entry": {
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "partner-network.com",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Temporarily disabled during vendor security audit",
    "source": "manual",
    "is_active": false,
    "allowed_count": 12,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:15:00.000Z"
  }
}

DELETE /v1/sender-rules/whitelist — Delete Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Permanently deletes an allowlist rule from your workspace.

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Unique identifier of the allowlist rule to delete.

Example Request

curl -X DELETE "https://api.aliasfleet.com/v1/sender-rules/whitelist?id=3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)

{
  "success": true,
  "message": "Removed from whitelist"
}

GET /v1/sender-rules/whitelist/stats — Allowlist Metrics & Trends

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns aggregated statistics regarding allowlist rule counts, lifetime forwarded volumes, and monthly trends.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/whitelist/stats" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "stats": {
    "totalRules": 14,
    "activeRules": 12,
    "rulesTrend": 20,
    "totalAllowedEmails": 384,
    "newThisMonth": 3
  }
}

GET /v1/sender-rules/blacklist — List Blocked Sender Rules

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns a paginated list of blocked sender rules (denylist) configured for your workspace.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Number of records per page (max `100`).
`search`	`string`	Optional	—	Case-insensitive filter on `email_pattern`.
`includeGlobal`	`boolean`	Optional	`false`	When `true`, includes platform-wide threat network rules alongside workspace rules.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/blacklist?page=1&limit=2" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "entries": [
    {
      "id": "b1a2b3c4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "user_id": "usr_9f8e7d6c5b4a3a2b",
      "email_pattern": "spammer.org",
      "pattern_type": "domain",
      "include_subdomains": true,
      "reason": "Phishing domain targeting credentials",
      "source": "manual",
      "is_active": true,
      "blocked_count": 142,
      "created_at": "2026-08-15T09:30:00.000Z",
      "updated_at": "2026-08-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 1,
    "totalPages": 1
  }
}

POST /v1/sender-rules/blacklist — Create Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 30/min · Idempotent: Yes

Creates an inbound denylist rule to reject messages from a specific address, domain, or wildcard pattern. Blocked messages are rejected at the edge without entering your forwarding stream.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`emailPattern`	`string`	Yes	1–255 chars	Email (`bad@spam.com`), domain (`spammer.org`), or wildcard pattern (`@.phishing.com`).
`patternType`	`string`	Optional	`exact`, `domain`, `pattern`	Matching mode. Auto-promoted to `domain` or `pattern` if pattern characters (`*`, `@`) are detected.
`includeSubdomains`	`boolean`	Optional	Boolean	When `true` with `patternType: "domain"`, blocks all subdomains (e.g. `*.spammer.org`).
`reason`	`string`	Optional	Max 255 chars	Rationale or internal audit comment.
`source`	`string`	Optional	Max 50 chars	Origin tag: `manual`, `quick_action`, `automated_filter`, or `api`. Defaults to `manual`.

Example Request

curl -X POST "https://api.aliasfleet.com/v1/sender-rules/blacklist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "emailPattern": "scamnetwork.xyz",
    "patternType": "domain",
    "includeSubdomains": true,
    "reason": "Persistent scam outreach campaign"
  }'

Response (`201 Created`)

{
  "success": true,
  "entry": {
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "scamnetwork.xyz",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Persistent scam outreach campaign",
    "source": "manual",
    "is_active": true,
    "blocked_count": 0,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:00:00.000Z"
  },
  "message": "scamnetwork.xyz has been blacklisted"
}

Errors

Status	Code	Cause & Resolution
`400 Bad Request`	`INVALID_PATTERN`	The pattern syntax does not conform to RFC email or hostname specifications.
`402 Payment Required`	`ENTITLEMENT_REQUIRED`	Domain and wildcard pattern rules require a Pro or Business subscription.
`409 Conflict`	`CROSS_TABLE_CONFLICT`	Pattern already exists on your allowlist (whitelist). Remove it from the allowlist first.
`409 Conflict`	`ALREADY_EXISTS`	Pattern is already present in your denylist.

PATCH /v1/sender-rules/blacklist — Update Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Updates an existing blocked sender rule, allowing you to toggle rule enforcement on or off without deleting the rule history and counters.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`id`	`string`	Yes	Rule UUID	Unique identifier of the denylist rule to modify.
`isActive`	`boolean`	Optional	Boolean	Activates or pauses rule enforcement.
`reason`	`string`	Optional	Max 255 chars	Updated note or rationale.
`includeSubdomains`	`boolean`	Optional	Boolean	Whether domain matching extends to subdomains.

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/sender-rules/blacklist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "isActive": false,
    "reason": "Deactivated pending review of false positive"
  }'

Response (`200 OK`)

{
  "success": true,
  "entry": {
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "scamnetwork.xyz",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Deactivated pending review of false positive",
    "source": "manual",
    "is_active": false,
    "blocked_count": 27,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:20:00.000Z"
  }
}

DELETE /v1/sender-rules/blacklist — Delete Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Permanently deletes a blocked sender rule from your workspace. Messages from the sender will once again be evaluated according to standard forwarding rules.

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Unique identifier of the denylist rule to delete.

Example Request

curl -X DELETE "https://api.aliasfleet.com/v1/sender-rules/blacklist?id=e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)

{
  "success": true,
  "message": "Removed from blacklist"
}

GET /v1/sender-rules/blacklist/stats — Denylist Metrics & Trends

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns aggregated statistics regarding blocked sender rules, lifetime rejected messages, and month-over-month threat volume trends.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/blacklist/stats" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "total": 35,
  "active": 32,
  "totalBlocked": 1842,
  "newThisMonth": 6,
  "newLastMonth": 4,
  "blacklistTrend": 50,
  "blockedTrend": -12,
  "blockedThisMonth": 210,
  "blockedLastMonth": 238
}

Frequently Asked Questions

Can a sender exist on both the allowlist and the denylist?

No. The firewall enforces strict mutual exclusivity. Creating a rule for an entry that exists in the opposing table returns HTTP 409 CROSS_TABLE_CONFLICT.

How fast are newly created rules enforced on incoming emails?

Rules propagate to the inbound firewall immediately. Incoming SMTP transactions from blocked senders are rejected in real time during the initial envelope handshake.

What wildcard pattern formats are supported?

Wildcard patterns support asterisk (*) and question mark (?) wildcards on local parts and domain extensions (e.g. *@*.spamnetwork.com, user*@domain.com, or *.badsite.xyz).

Are wildcard and domain rules available on all plans?

Exact email address rules are supported on all tiers. Domain-wide and wildcard pattern rules require a Pro or Business subscription.

Configure inbound email firewall rules to allowlist trusted senders or reject unwanted addresses, full domains, and wildcard patterns at the network edge.

Quick Reference

Endpoint	Method	Scope	Purpose
`/v1/sender-rules/whitelist`	`GET`	`sender_rules:read`	List configured allowed sender rules
`/v1/sender-rules/whitelist`	`POST`	`sender_rules:write`	Create an allowlist rule for an address, domain, or pattern
`/v1/sender-rules/whitelist`	`PATCH`	`sender_rules:write`	Toggle or update an allowlist rule
`/v1/sender-rules/whitelist`	`DELETE`	`sender_rules:write`	Delete an allowlist rule
`/v1/sender-rules/whitelist/stats`	`GET`	`sender_rules:read`	Retrieve allowlist volume and monthly trend metrics
`/v1/sender-rules/blacklist`	`GET`	`sender_rules:read`	List configured blocked sender rules
`/v1/sender-rules/blacklist`	`POST`	`sender_rules:write`	Create a denylist rule to reject senders or domains
`/v1/sender-rules/blacklist`	`PATCH`	`sender_rules:write`	Toggle or update a denylist rule
`/v1/sender-rules/blacklist`	`DELETE`	`sender_rules:write`	Delete a denylist rule
`/v1/sender-rules/blacklist/stats`	`GET`	`sender_rules:read`	Retrieve blocked volume and monthly trend metrics

Inbound Firewall Architecture

The AliasFleet Inbound Firewall evaluates incoming messages at the earliest possible stage of the email delivery pipeline:

Edge Rejection: When an inbound SMTP transaction arrives from a blocked sender or domain, the firewall terminates the session during the MAIL FROM envelope handshake with an RFC 5321 550 5.7.1 permanent failure code. The message body is never accepted or stored.
Mutual Exclusivity Invariant: A sender pattern cannot exist on both your allowlist and your denylist. If you attempt to allow an address that is currently blocked, the API rejects the request with CROSS_TABLE_CONFLICT.
Pattern Matching Hierarchy:
- Exact: Matches specific email addresses (spammer@example.com).
- Domain: Matches all senders under a domain (badcompany.com), with optional recursive subdomain coverage (includeSubdomains: true).
- Pattern: Advanced wildcard matching (*@promo.*.com, alert*@monitoring.internal).

GET /v1/sender-rules/whitelist — List Allowed Sender Rules

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns a paginated list of allowed sender rules configured for your workspace.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Number of records per page (max `100`).
`search`	`string`	Optional	—	Case-insensitive filter on `email_pattern`.
`includeGlobal`	`boolean`	Optional	`false`	When `true`, includes platform-wide system rules alongside workspace rules.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/whitelist?page=1&limit=2" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "entries": [
    {
      "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "user_id": "usr_9f8e7d6c5b4a3a2b",
      "email_pattern": "vip-notifications@partner.com",
      "pattern_type": "exact",
      "include_subdomains": false,
      "reason": "Critical billing and invoice updates",
      "source": "manual",
      "is_active": true,
      "allowed_count": 48,
      "created_at": "2026-08-20T10:00:00.000Z",
      "updated_at": "2026-08-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 1,
    "totalPages": 1
  }
}

POST /v1/sender-rules/whitelist — Create Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 30/min · Idempotent: Yes

Adds a sender address, domain, or wildcard pattern to your inbound allowlist.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`emailPattern`	`string`	Yes	1–255 chars	Email (`user@domain.com`), domain (`partner.com`), or wildcard pattern (`@.corp.com`).
`patternType`	`string`	Optional	`exact`, `domain`, `pattern`	Pattern evaluation strategy. Defaults to `exact`.
`includeSubdomains`	`boolean`	Optional	Boolean	When `true` with `patternType: "domain"`, matches subdomains (e.g. `*.partner.com`).
`reason`	`string`	Optional	Max 255 chars	Contextual note explaining why the sender is allowlisted.
`source`	`string`	Optional	Max 50 chars	Origin tag: `manual`, `quick_action`, or `api`. Defaults to `manual`.

Example Request

curl -X POST "https://api.aliasfleet.com/v1/sender-rules/whitelist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "emailPattern": "partner-network.com",
    "patternType": "domain",
    "includeSubdomains": true,
    "reason": "Authorized B2B syndication partner"
  }'

Response (`201 Created`)

{
  "success": true,
  "entry": {
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "partner-network.com",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Authorized B2B syndication partner",
    "source": "manual",
    "is_active": true,
    "allowed_count": 0,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:00:00.000Z"
  },
  "message": "partner-network.com has been added to the allowlist"
}

Errors

Status	Code	Cause & Resolution
`400 Bad Request`	`INVALID_PATTERN`	The `emailPattern` string is malformed or invalid syntax.
`402 Payment Required`	`ENTITLEMENT_REQUIRED`	Domain and wildcard rules require a Pro or Business plan.
`409 Conflict`	`CROSS_TABLE_CONFLICT`	The pattern already exists on your denylist (blacklist). Remove it from the denylist first.
`409 Conflict`	`ALREADY_EXISTS`	The pattern is already present on your allowlist.

PATCH /v1/sender-rules/whitelist — Update Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Toggles the active state or updates the description metadata for an existing allowlist rule.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`id`	`string`	Yes	Rule UUID	Unique identifier of the rule to modify.
`isActive`	`boolean`	Optional	Boolean	Activates or pauses rule enforcement.
`reason`	`string`	Optional	Max 255 chars	Updated note or rationale.
`includeSubdomains`	`boolean`	Optional	Boolean	Whether domain matching extends to subdomains.

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/sender-rules/whitelist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "isActive": false,
    "reason": "Temporarily disabled during vendor security audit"
  }'

Response (`200 OK`)

{
  "success": true,
  "entry": {
    "id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "partner-network.com",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Temporarily disabled during vendor security audit",
    "source": "manual",
    "is_active": false,
    "allowed_count": 12,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:15:00.000Z"
  }
}

DELETE /v1/sender-rules/whitelist — Delete Allowed Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Permanently deletes an allowlist rule from your workspace.

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Unique identifier of the allowlist rule to delete.

Example Request

curl -X DELETE "https://api.aliasfleet.com/v1/sender-rules/whitelist?id=3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)

{
  "success": true,
  "message": "Removed from whitelist"
}

GET /v1/sender-rules/whitelist/stats — Allowlist Metrics & Trends

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns aggregated statistics regarding allowlist rule counts, lifetime forwarded volumes, and monthly trends.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/whitelist/stats" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "stats": {
    "totalRules": 14,
    "activeRules": 12,
    "rulesTrend": 20,
    "totalAllowedEmails": 384,
    "newThisMonth": 3
  }
}

GET /v1/sender-rules/blacklist — List Blocked Sender Rules

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns a paginated list of blocked sender rules (denylist) configured for your workspace.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`integer`	Optional	`1`	Page number for pagination.
`limit`	`integer`	Optional	`50`	Number of records per page (max `100`).
`search`	`string`	Optional	—	Case-insensitive filter on `email_pattern`.
`includeGlobal`	`boolean`	Optional	`false`	When `true`, includes platform-wide threat network rules alongside workspace rules.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/blacklist?page=1&limit=2" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "entries": [
    {
      "id": "b1a2b3c4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "user_id": "usr_9f8e7d6c5b4a3a2b",
      "email_pattern": "spammer.org",
      "pattern_type": "domain",
      "include_subdomains": true,
      "reason": "Phishing domain targeting credentials",
      "source": "manual",
      "is_active": true,
      "blocked_count": 142,
      "created_at": "2026-08-15T09:30:00.000Z",
      "updated_at": "2026-08-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 1,
    "totalPages": 1
  }
}

POST /v1/sender-rules/blacklist — Create Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 30/min · Idempotent: Yes

Creates an inbound denylist rule to reject messages from a specific address, domain, or wildcard pattern. Blocked messages are rejected at the edge without entering your forwarding stream.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`emailPattern`	`string`	Yes	1–255 chars	Email (`bad@spam.com`), domain (`spammer.org`), or wildcard pattern (`@.phishing.com`).
`patternType`	`string`	Optional	`exact`, `domain`, `pattern`	Matching mode. Auto-promoted to `domain` or `pattern` if pattern characters (`*`, `@`) are detected.
`includeSubdomains`	`boolean`	Optional	Boolean	When `true` with `patternType: "domain"`, blocks all subdomains (e.g. `*.spammer.org`).
`reason`	`string`	Optional	Max 255 chars	Rationale or internal audit comment.
`source`	`string`	Optional	Max 50 chars	Origin tag: `manual`, `quick_action`, `automated_filter`, or `api`. Defaults to `manual`.

Example Request

curl -X POST "https://api.aliasfleet.com/v1/sender-rules/blacklist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "emailPattern": "scamnetwork.xyz",
    "patternType": "domain",
    "includeSubdomains": true,
    "reason": "Persistent scam outreach campaign"
  }'

Response (`201 Created`)

{
  "success": true,
  "entry": {
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "scamnetwork.xyz",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Persistent scam outreach campaign",
    "source": "manual",
    "is_active": true,
    "blocked_count": 0,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:00:00.000Z"
  },
  "message": "scamnetwork.xyz has been blacklisted"
}

Errors

Status	Code	Cause & Resolution
`400 Bad Request`	`INVALID_PATTERN`	The pattern syntax does not conform to RFC email or hostname specifications.
`402 Payment Required`	`ENTITLEMENT_REQUIRED`	Domain and wildcard pattern rules require a Pro or Business subscription.
`409 Conflict`	`CROSS_TABLE_CONFLICT`	Pattern already exists on your allowlist (whitelist). Remove it from the allowlist first.
`409 Conflict`	`ALREADY_EXISTS`	Pattern is already present in your denylist.

PATCH /v1/sender-rules/blacklist — Update Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Updates an existing blocked sender rule, allowing you to toggle rule enforcement on or off without deleting the rule history and counters.

Request Body Parameters

Parameter	Type	Required	Constraints	Description
`id`	`string`	Yes	Rule UUID	Unique identifier of the denylist rule to modify.
`isActive`	`boolean`	Optional	Boolean	Activates or pauses rule enforcement.
`reason`	`string`	Optional	Max 255 chars	Updated note or rationale.
`includeSubdomains`	`boolean`	Optional	Boolean	Whether domain matching extends to subdomains.

Example Request

curl -X PATCH "https://api.aliasfleet.com/v1/sender-rules/blacklist" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "isActive": false,
    "reason": "Deactivated pending review of false positive"
  }'

Response (`200 OK`)

{
  "success": true,
  "entry": {
    "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "user_id": "usr_9f8e7d6c5b4a3a2b",
    "email_pattern": "scamnetwork.xyz",
    "pattern_type": "domain",
    "include_subdomains": true,
    "reason": "Deactivated pending review of false positive",
    "source": "manual",
    "is_active": false,
    "blocked_count": 27,
    "created_at": "2026-09-04T12:00:00.000Z",
    "updated_at": "2026-09-04T12:20:00.000Z"
  }
}

DELETE /v1/sender-rules/blacklist — Delete Blocked Sender Rule

Scope: sender_rules:write · Rate Limit: 60/min · Idempotent: Yes

Permanently deletes a blocked sender rule from your workspace. Messages from the sender will once again be evaluated according to standard forwarding rules.

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Unique identifier of the denylist rule to delete.

Example Request

curl -X DELETE "https://api.aliasfleet.com/v1/sender-rules/blacklist?id=e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e"

Response (`200 OK`)

{
  "success": true,
  "message": "Removed from blacklist"
}

GET /v1/sender-rules/blacklist/stats — Denylist Metrics & Trends

Scope: sender_rules:read · Rate Limit: 60/min · Idempotent: Yes

Returns aggregated statistics regarding blocked sender rules, lifetime rejected messages, and month-over-month threat volume trends.

Example Request

curl -X GET "https://api.aliasfleet.com/v1/sender-rules/blacklist/stats" \
  -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \
  -H "Accept: application/json"

Response (`200 OK`)

{
  "total": 35,
  "active": 32,
  "totalBlocked": 1842,
  "newThisMonth": 6,
  "newLastMonth": 4,
  "blacklistTrend": 50,
  "blockedTrend": -12,
  "blockedThisMonth": 210,
  "blockedLastMonth": 238
}

Quick Reference

Inbound Firewall Architecture

GET /v1/sender-rules/whitelist — List Allowed Sender Rules

Query Parameters

Example Request

Response (200 OK)

POST /v1/sender-rules/whitelist — Create Allowed Sender Rule

Request Body Parameters

Example Request

Response (201 Created)

Errors

PATCH /v1/sender-rules/whitelist — Update Allowed Sender Rule

Request Body Parameters

Example Request

Response (200 OK)

DELETE /v1/sender-rules/whitelist — Delete Allowed Sender Rule

Query Parameters

Example Request

Response (200 OK)

GET /v1/sender-rules/whitelist/stats — Allowlist Metrics & Trends

Example Request

Response (200 OK)

GET /v1/sender-rules/blacklist — List Blocked Sender Rules

Query Parameters

Example Request

Response (200 OK)

POST /v1/sender-rules/blacklist — Create Blocked Sender Rule

Request Body Parameters

Example Request

Response (201 Created)

Errors

PATCH /v1/sender-rules/blacklist — Update Blocked Sender Rule

Request Body Parameters

Example Request

Response (200 OK)

DELETE /v1/sender-rules/blacklist — Delete Blocked Sender Rule

Query Parameters

Example Request

Response (200 OK)

GET /v1/sender-rules/blacklist/stats — Denylist Metrics & Trends

Example Request

Response (200 OK)

Frequently Asked Questions

Can a sender exist on both the allowlist and the denylist?

How fast are newly created rules enforced on incoming emails?

What wildcard pattern formats are supported?

Are wildcard and domain rules available on all plans?

Was this article helpful?

Related articles

Identity & Token Introspection API

Aliases API

Alias Destinations & Batch Operations API

Domains API

Destinations API

Still need help?

Quick Reference

Inbound Firewall Architecture

GET /v1/sender-rules/whitelist — List Allowed Sender Rules

Query Parameters

Example Request

Response (200 OK)

POST /v1/sender-rules/whitelist — Create Allowed Sender Rule

Request Body Parameters

Example Request

Response (201 Created)

Errors

PATCH /v1/sender-rules/whitelist — Update Allowed Sender Rule

Request Body Parameters

Example Request

Response (200 OK)

DELETE /v1/sender-rules/whitelist — Delete Allowed Sender Rule

Query Parameters

Example Request

Response (200 OK)

GET /v1/sender-rules/whitelist/stats — Allowlist Metrics & Trends

Example Request

Response (200 OK)

GET /v1/sender-rules/blacklist — List Blocked Sender Rules

Query Parameters

Example Request

Response (`200 OK`)

Response (`201 Created`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`201 Created`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`201 Created`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`200 OK`)

Response (`201 Created`)

Response (`200 OK`)

Response (`200 OK`)