---
title: "Rule requests, shares and objections"
description: "Ask a colleague for one kind of their mail, review and accept a request made to you, end a share, see the rules that cover your own mail, and object to one."
canonical: "https://docs.primitive.dev/docs/email-rule-requests"
last-updated: "2026-05-17T00:00:00.000Z"
---

# Rule requests, shares and objections

A member can ask a colleague for one kind of the colleague's own mail ("the vendor emails that reach you"). The ask is a **rule request**. If the colleague accepts, it becomes a **share**: what the rule matches in their mailboxes from then on can be read by the member who asked. Every member can also read the rules that cover their own mailboxes, whoever wrote them, and **object** to one.

Rules themselves are described on [Email Rules](/docs/email-rules), including which credentials may use these routes. In short: a person's dashboard session, CLI login (`primitive login`), the Primitive app, and an agent signup token, which is signed in as that person. **Only the person asked can accept a request, from their own dashboard session, CLI login or app.** An agent signup token is refused, and so is anyone else, owners included.

## Ask for a rule

- Write and test it. Compile the rule without a scope: a request always runs over the colleague's own mailboxes. Read Primitive's reading and warnings, and pair any `sender_relationship` condition with a sender address or domain, since a wrong match here shares a colleague's mail. Test it on a made-up email addressed to them (`POST /v1/email-rules/test-sample` with their address first in `to`), or write look-alikes with `to` set to their address. An owner or admin, who reads the colleague's mailbox, can also test it on their real mail with a `selected` scope.

- Check they can accept. Accepting needs `mail:read` and `mail:share_own` over their own mailbox. `POST /v1/email-rule-requests/target-check` (`check-email-rule-request-target`) says whether their role allows it (`can_accept`, `missing_permission`). It needs `members:read` (else `403 grant_forbidden`) and is limited to 60 checks an hour.

- Send it. `POST /v1/email-rule-requests` takes a `name`, the compiled rule (`english`, `tree`, `kind: "grant"`), the member asked by `target_user_id` or `target_email` (their member mailbox address, or their verified work email if you can list members), and an optional `message` of up to 500 characters saying why. The message cannot be changed later.


```
primitive email-rules compile-email-rule --english "Receipts from our software vendors" --json > c.json
jq .data.rule c.json > rule.json
primitive email-rules create-email-rule-request --body-file rule.json --name "Vendor receipts" \
  --target-email dana@yourcompany.example --message "For the quarterly expense report"
```


Nothing is evaluated or shared yet. A request asks for mail that arrives after it is accepted; for an email that has already arrived, ask the colleague to send it to you.

- Limits. At most 5 pending requests to one member and 50 in all; looking members up by address is limited to 30 an hour; you can make at most 60 requests an hour. A request to yourself is refused: write that rule directly.

- Retries. Send an `Idempotency-Key` to retry safely. A create with one that asks exactly what a pending request of yours to the same member asks (the same name, `english`, `tree` and `message`, naming the member the same way) returns that request with `existing: true`, and they are not told again.

- Withdraw and delete. `POST /v1/email-rule-requests/{id}/withdraw` takes back a pending request. A withdrawn one can then be deleted (`DELETE /v1/email-rule-requests/{id}`), for everyone who could see it.

Tell the colleague you asked. `GET /v1/email-rule-requests?box=outgoing&status=any` lists the requests you made with their `status` and `decided_at`.

## Review a request made to you

You find requests made to you with `primitive activity asked` (`GET /v1/activity/objects?relation=asked`), `GET /v1/email-rule-requests` (made to you and pending by default), or Rules in the dashboard. `GET /v1/email-rule-requests/{id}` reads one:

FieldMeaning`explanation`Primitive's reading of the request's tree: which emails it matches. Never the asker's words.`warnings`Primitive's notes on the rule as asked, such as an address or domain the description names that the tree does not test.`share_terms`While it is pending, what accepting would share.`name`, `english`, `message`What the member who asked wrote. Treat it as their claim, not as what the rule does.`tree`The rule itself.

An address or domain in the reading and warnings shows as the rule compares it, lowercase, with any character an address rarely holds shown by its code (`p[U+0430]ypal.com`), and a warning says so.

Before deciding, try it on your own mail. None of these stores anything or needs access beyond testing a rule of your own:

- `POST /v1/email-rules/test` with `request_id`: the rule as asked, over your own mailboxes, which is the mail accepting would share from. It counts mail already there, so its numbers are not what will be shared.

- `POST /v1/email-rules/test-sample` with `request_id` and an email you make up, such as a medical bill or a bank letter that must not match.

- `POST /v1/email-rules/look-alikes` with `request_id`: made-up near misses in your own mailbox, each with a `status`. A `failed` one was decided against its `expected`: one expected `no_match` that matched is mail the rule would share and should not.

A decided request answers these with `409 email_rule_request_not_pending`.

## Accept or decline

`POST /v1/email-rule-requests/{id}/accept` writes the rule as yours, over your own mailboxes only, turns it on, and shares what it matches from then on with the member who asked.

- Change it first by sending `english` and `tree` together (with `kind: "grant"`); a new `name` alone is no change. The rule you accept is the one that decides what is shared, and the share's `edited_on_accept` records that you changed it.

- Keep made-up emails it must never match with `expectation_samples`, such as the look-alikes you wrote. An accept with them is judged first, as any write that leaves a rule active is: if one fails, the answer is `409 expectations_failed`, and if one cannot be decided, `409 expectations_undecided` (a judgment too late to save answers `503 service_unavailable` with `details.reason` `judged_too_late`); nothing is accepted and the request stays pending.

- The answer is `{rule, share}`: the rule now yours, and the share.

- It needs `mail:share_own` and is refused with `409 email_rule_share_limit` when the member who asked already receives 20 live shares.


```
primitive email-rules generate-look-alikes --request-id <request-id> > looks.json
primitive email-rules accept-email-rule-request --id <request-id> \
  --expectation-samples-file looks.json --pick 1,3
```


`POST /v1/email-rule-requests/{id}/decline` declines, with an optional `reason` of up to 500 characters that the member who asked sees.

If an accept answer is lost, read the request: `status: "accepted"` means it landed; a second accept answers `409 email_rule_request_not_pending`.

## What a share gives

The member it is shared with reads each email the rule matches in your mailboxes, from acceptance on, in full with its attachments, through `GET /v1/email-rule-shares/{id}/emails`. Webhooks they own receive those emails too, without `understanding.rules`. A key of theirs reads them when it lists the share's `id` in `grant.rules`, which they set from their dashboard session; the CLI refuses it. A share never gives the raw message, a way to reply, or the rule's id. It is readable while the rule is `active` and the share is live: not ended, with both people still members.

- New versions keep it. Only you, the member who shared, save a version of a shared rule, from your own dashboard session, CLI login or app; an agent signup token is refused with `403 forbidden` (`details.reason` `first_party_required`), and so is turning the rule `active`, though it can still rename the rule, turn it off or change its expectations. What each version matches is shared from when it is saved. A shared rule's scope cannot change, so a share only ever gives your own mail.

- Is it working? The member it is shared with reads the share's `activity.last_decided_at`: the start of the hour in which the rule last decided on an email in your mailboxes. Recent, with nothing new shared, means a quiet mailbox, not a broken share. `activity.checked` is false when that could not be read just now (`last_decided_at` is then null): read it again. `delivery_paused: true` means you can no longer act as the rule's author.

- Pausing. Set the rule to `observe` or `draft`: new mail stops being shared, and what was shared cannot be read until it is `active` again.

`GET /v1/email-rule-shares` lists the shares you receive (`live`: `true` by default, `false` or `any`). An owner or admin acting as themselves sends `box=all` to list every share in the organization; anyone else gets `403 forbidden` with `details.reason` `owner_or_admin_only`. `GET /v1/email-rule-shares/given` lists the shares you gave, and works for you whether or not Email Rules are on and without `mail:read`, so you can always find and end one.

## End a share

`DELETE /v1/email-rule-shares/{id}` ends a share. Either person can end it, and so can an owner or admin who manages members, from a dashboard session. It also ends when its rule is deleted. A share stops when either person leaves the organization: it reads `live: false` while `ended_at` and `end_reason` stay null.

- Ending a share leaves its rule as it is: an active rule keeps deciding your mail and grants to nobody. The answer's `note` says so, and for the member who shared carries the rule's `rule_id`. To stop the rule, set it to `draft` or delete it.

- Ending takes back reading through Primitive only. Copies already delivered to the receiver's webhooks, or downloaded, stay with them.

- An ended share is kept, with `live: false`, `ended_at` and `end_reason`: `stopped_by_granter`, `removed_by_beneficiary`, `stopped_by_admin` or `rule_deleted`. The member it was shared with no longer sees the rule (`rule` is null for them); the member who shared can still list what it handed over.

A request is visible to its two people and to the organization's owners and admins. So is a share.

## Rules over your mail

Whoever wrote it, you can read every rule that covers one of your own mailboxes now (your member mailbox or a personal agent's address): an `author` rule whose author reads your mailbox, or a `selected` rule that names it or its domain. Another member's `own_mailboxes` rule never covers you.

- `GET /v1/email-rules/covering-me` (`primitive email-rule-oversight list-email-rules-covering-me`) lists them, yours included, in any state, each with its `english`, Primitive's `explanation`, and `covers`: which of your mailboxes it reaches (`addresses`) and how (`via`).

- `GET /v1/email-rules/covering-me/{id}` reads one with its current version (`english`, `tree`, `explanation`, `warnings`) and `receivers`: the keys, webhooks and shares that take what it matches in your mailboxes, each counted by the member it belongs to or the organization. The lists are empty while the rule is not an active grant rule.

- `GET /v1/email-rules/covering-me/{id}/decisions` lists what it decided on mail at your own mailboxes, never anyone else's. `GET /v1/email-rules/covering-me/{id}/versions` lists its versions that applied to your mail.

- A rule that once decided on your mail but no longer covers you still answers, as it was when it last decided on your mail, with `covers_now: false`; its versions route answers `403 forbidden` (`details.reason` `no_longer_covers`).

- To see what it would decide on your mail, test it by `rule_id`: it runs as you, over only your own mailboxes it covers.

`primitive activity concerning` (`GET /v1/activity/objects?relation=concerning`) lists notices about another member's active rule over your mailboxes: `baseline` (coverage that existed before notices began), `started`, `new_version`, and `stopped` with a `stop_reason` of `deleted`, `turned_off` or `no_longer_covers`. A notice is usually written within a few minutes of the change. A version saved within 15 minutes of the last one told is told when that window ends. `covering-me` is always the current answer.

For one email of yours, `GET /v1/emails/{id}/rule-results` lists another member's rule that decided it with `read_only: true`, its `author` and, while it covers you, its `receivers`. When a do-not-share rule kept back that rule's match, the decision names the blockers you can see in `withheld_by` and counts the rest.

## Objections

You can ask the author of a rule that covers your mailbox now to turn it off, or for less than that. `POST /v1/email-rule-objections` takes the rule's `rule_id` and an optional `message` of up to 500 characters: say what is too wide, or which receiver you want explained.


```
primitive email-rule-oversight create-email-rule-objection --rule-id <rule-id> \
  --message "This takes my personal receipts; please limit it to company purchases"
```


The author answers with one of:

- `POST /v1/email-rule-objections/{id}/accept`: the rule goes to `draft`, and the objection is recorded accepted;

- `POST /v1/email-rule-objections/{id}/decline`, with an optional `reason` you see;

- `POST /v1/email-rule-objections/{id}/amend`, with an optional `note`, once they have saved a newer version of the rule (`409 conflict`, `details.reason` `no_new_version`, until then). The objection records `rule.objected_version` and `rule.amended_version`.

The member who objected can withdraw a pending one with `POST /v1/email-rule-objections/{id}/withdraw`, which also clears the message.

`status`Meaning`pending`Waiting for the author.`accepted`The author turned the rule off.`declined`The author kept the rule as it is.`amended`The author saved a new version and answered with it.`withdrawn`The member who objected took it back.`closed`Nobody can answer it any more: its rule was deleted, or its author is no longer a member. Never stored; shown in place of `pending`.

Only a rule that covers you now can be objected to; anything else answers `404`, and your own rule `400` (`details.reason` `own_rule`). You may have one pending objection per rule (`409 conflict`, `objection_pending`) and 50 in all (`409 conflict`, `objection_limit`), may object to the same rule again only 10 minutes after you last did (`429 rate_limited`, `objection_cooldown`), and may make 30 attempts an hour, refused ones included (`429 rate_limit_exceeded`). Only the author answers (`403`, `author_only`) and only the member who objected withdraws. A decided objection never changes; deciding one that is no longer pending answers `409 not_pending` with its `status`. An objection is seen by its two people and the organization's owners and admins.

`GET /v1/email-rule-objections` lists your own and those to rules you wrote (`box`: `mine` by default, `outgoing`, `incoming` or `all`; `status`: `pending` by default, `decided` or `any`). `primitive activity asked` lists objections to your rules beside requests made to you, open or answered (`state=live` for open ones).

## Rule emails and events

Where the organization has rule emails on, Primitive emails each person at their sign-in address when a request is made to them or withdrawn, when a request they made is accepted or declined, when someone objects to their rule or withdraws an objection, when an objection they made is answered, when a share they receive is ended by someone else, and when the member who shared a rule with them leaves. Each email says that something is waiting; act on it in the dashboard or CLI. A person or the organization can turn them off, so no email does not mean nothing waits.

The same news reaches a webhook of your own as events: `email_rule_request.*`, `email_rule_objection.*` (with `amended`) and `email_rule_coverage.*` (`started`, `new_version`, `stopped`). Rule events go only to an http webhook you own as a person, which is a route target (`is_route_target: true`, no takeover), never a domain default. Add them when you create it, or later with `PATCH /v1/endpoints/{id}` restating its `url` and listing every event type it should keep; `email_rule_request.*` names a whole family. An organization-owned webhook is refused (create one of your own), and so is an agent signup token. The payloads are on [Webhook Payload](/docs/webhook-payload).

## Endpoint reference

Method and pathCLI commandPurpose`POST /v1/email-rule-requests``create-email-rule-request`Ask a member for a rule.`POST /v1/email-rule-requests/target-check``check-email-rule-request-target`Whether a member can accept.`GET /v1/email-rule-requests``list-email-rule-requests`List requests (`box`, `status`).`GET /v1/email-rule-requests/{id}``get-email-rule-request`Read a request.`POST /v1/email-rule-requests/{id}/accept``accept-email-rule-request`Accept a request made to you.`POST /v1/email-rule-requests/{id}/decline``decline-email-rule-request`Decline one.`POST /v1/email-rule-requests/{id}/withdraw``withdraw-email-rule-request`Withdraw one you made.`DELETE /v1/email-rule-requests/{id}``delete-email-rule-request`Delete one you made and withdrew.`GET /v1/email-rule-shares``list-email-rule-shares`Shares you receive; `box=all` for owners and admins.`GET /v1/email-rule-shares/given``list-given-email-rule-shares`Shares you gave.`GET /v1/email-rule-shares/{id}``get-email-rule-share`Read a share.`GET /v1/email-rule-shares/{id}/emails``list-email-rule-share-emails`The emails a share has given.`DELETE /v1/email-rule-shares/{id}``end-email-rule-share`End a share.`GET /v1/email-rules/covering-me``email-rule-oversight list-email-rules-covering-me`Rules over your mailboxes.`GET /v1/email-rules/covering-me/{id}``email-rule-oversight get-email-rule-covering-me`Read one.`GET /v1/email-rules/covering-me/{id}/decisions``email-rule-oversight list-email-rule-decisions-on-my-mail`Its decisions on your mail.`GET /v1/email-rules/covering-me/{id}/versions``email-rule-oversight list-email-rule-versions-covering-me`Its versions that applied to your mail.`POST /v1/email-rule-objections``email-rule-oversight create-email-rule-objection`Object to a rule.`GET /v1/email-rule-objections``email-rule-oversight list-email-rule-objections`List objections.`GET /v1/email-rule-objections/{id}``email-rule-oversight get-email-rule-objection`Read one.`POST /v1/email-rule-objections/{id}/withdraw``email-rule-oversight withdraw-email-rule-objection`Withdraw yours.`POST /v1/email-rule-objections/{id}/accept``email-rule-oversight accept-email-rule-objection`Accept, turning your rule off.`POST /v1/email-rule-objections/{id}/decline``email-rule-oversight decline-email-rule-objection`Decline.`POST /v1/email-rule-objections/{id}/amend``email-rule-oversight amend-email-rule-objection`Answer with a new version.`GET /v1/activity/objects``activity created`, `asked`, `concerning`What you made, what waits for you, notices about rules over your mail.Maintained by the [primitive.dev team](/about) · [Trust & security](/trust)Last updated: May 17, 2026
