---
title: "List send-permission rules"
method: GET
path: "/send-permissions"
tags: ["Sending"]
---

# List send-permission rules

`GET /send-permissions`

Returns a flat list of rules describing every recipient the
caller may send to. Each rule has a `type`, a kind-specific
payload, and a human-readable `description`. If any rule
matches the recipient, /send-mail will accept the send under
the recipient-scope check.

The endpoint is the answer to "where can I send" without
exposing internal entitlement names. Agents that don't
recognize a `type` can still read the `description` prose
and act on it.

Rule kinds, ordered broadest-first so an agent can stop
scanning at the first match:

  1. `any_recipient` (one entry, only when the org can send
     anywhere): every other rule below it is redundant.
  2. `managed_zone` (always emitted, one per Primitive-managed
     zone): sends to any address at *.primitive.email or
     *.email.works always succeed; no entitlement required.
  3. `your_domain` (one per active verified outbound domain
     owned by the org): sends to that domain are approved.
  4. `address` (one per address that has authenticated
     inbound mail to the org, capped at `meta.address_cap`):
     sends to that exact address are approved.

The list is informational, not an authorization check.
/send-mail remains the source of truth on whether an
individual send will succeed (it also enforces the
from-address and the `send_mail` entitlement, which are
not recipient-scope concerns and are not represented here).

## Response `200`

Send-permission rules for the caller's org

- object
  - `success` true, required
  - `data` union[], required
    - union — One recipient-scope rule describing a destination the caller may send to. Discriminated on `type`. Each rule carries a human-prose `description` field intended for display. Rule kinds are stable within an SDK release. A response containing a `type` value not enumerated in this schema means the server is running a newer version than the SDK; upgrade the SDK to the release that matches the server's schema. Strict-parsing SDKs (Go, Python) will raise a decode error in that case rather than silently dropping the unknown rule, since silent drops would let an outbound agent reason from an incomplete view of its own permissions.
      - object — The caller can send to any recipient. When this rule is present, every other rule in the response is redundant.
        - `type` 'any_recipient', required
        - `description` string, required — Human-prose summary of the rule.
      - object — The caller can send to any address at the named Primitive-managed zone. Always emitted (no entitlement required) because Primitive owns the zone and every mailbox belongs to a Primitive customer by construction.
        - `type` 'managed_zone', required
        - `zone` string, required — The managed apex domain. Sends are accepted to any address at the apex itself or any subdomain (e.g. `alice@primitive.email` and `alice@acme.primitive.email` both match the `primitive.email` zone rule).
        - `description` string, required — Human-prose summary of the rule.
      - object — The caller can send to any address at one of their own verified outbound domains. Emitted once per active row in the org's `domains` table.
        - `type` 'your_domain', required
        - `domain` string, required — A verified outbound domain owned by the caller's org.
        - `description` string, required — Human-prose summary of the rule.
      - object — The caller can send to a specific address that has authenticated inbound mail to the org. Emitted once per row in the org's `known_send_addresses` table, capped at `meta.address_cap`.
        - `type` 'address', required
        - `address` string, required — The bare email address this rule grants sends to.
        - `last_received_at` string, date-time, required — Most recent inbound email from this address that authenticated successfully (DMARC pass + DKIM/SPF alignment). Updated on each new authenticated receipt.
        - `received_count` integer, required — Total number of authenticated inbound emails from this address. Increments only when `last_received_at` advances.
        - `description` string, required — Human-prose summary of the rule.
  - `meta` object, required — Response metadata for /send-permissions. The `address_cap` bounds the size of the `address` rule subset; orgs with more than `address_cap` known addresses almost always also hold a broader rule type (`any_recipient` or `your_domain`), so the cap is a response-size bound rather than a meaningful product limit.
    - `address_cap` integer, required — Maximum number of `address` rules included in `data`.
    - `truncated` boolean, required — True when the org has more than `address_cap` known addresses and the list was truncated. False when every known address is represented or when the org holds no address rules at all.

## Other responses

- `401` — Invalid or missing API key

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)