Managing Domains and Recipient Routes

Use the primitive routes command group to control which endpoint or Primitive Function handles inbound mail for a given recipient address, and primitive domains-zone-file to check the DNS records your inbound domain needs. You need this whenever you want per-address routing (alice@acme.com goes to one function, everyone else falls through to a default) instead of a single catch-all inbox.

Recipient routing is gated by an organization entitlement. Routes you create are inert until that entitlement is enabled on your org.

Check domain DNS#

Before mail can route anywhere, your inbound domain needs the right DNS records. Print the zone file entries for your inbound domain with primitive domains-zone-file, the command that emits the DNS records Primitive needs to receive mail for that domain:

primitive domains-zone-file

Add the printed records at your DNS provider, then confirm the domain status with primitive domains list or primitive inbox-status. Run primitive domains-zone-file --help for the exact flag list, and primitive domains --help for the rest of the domain lifecycle commands.

Add a recipient route#

1. 1

   Decide the destination: a function or an existing endpoint#

   Routing an address to a Primitive Function creates that function's route-target endpoint for you in the same call, so --function <function-id> is the shortest path. Routing to an existing endpoint with --endpoint <endpoint-id> requires you to know the endpoint id up front.

2. 2

   Add an exact-match route#

   Bind one address to a function:

   primitive routes add alice@acme.com --function <function-id>
   

   Bind one address to an existing endpoint instead:

   primitive routes add ops@acme.com --endpoint <endpoint-id>
   

3. 3

   Add a wildcard route for a pattern of addresses#

   Pass --match wildcard to route every address matching a pattern, for example every support+*@acme.com alias:

   primitive routes add 'support+*@acme.com' --match wildcard --endpoint <endpoint-id>
   

   Quote wildcard patterns so your shell doesn't expand the *.

4. 4

   Confirm the rule exists#

   primitive routes list
   

   Expect the new rule in the output with its priority, match type, and destination.

Preview where an address resolves#

Before mail actually arrives, verify which rule wins for a given address and see the rule trace:

primitive routes test alice@acme.com

Expected output includes the winning rule (or explicit fallback if no rule matches) and the ordered list of rules that were evaluated. Use this to debug overlapping wildcard and exact rules without waiting for a real inbound email.

Change rule priority#

Routing rules are evaluated in priority order. Update a single rule's priority:

primitive routes update <route-id> --priority 5

Reorder several rules in one call by setting an explicit priority per rule id:

primitive routes reorder --set <route-id>=10 --set <other-id>=20

Confirm the resulting order with primitive routes list, and check the effect on a specific address with primitive routes test.

Remove a route#

primitive routes remove <route-id>

Next steps#