JMAP sender lists

This page defines a small JMAP extension. Its capability is named by this page’s address:

https://nixtoffice.com/docs/server/jmap-sender-list

With it, an app keeps the list of senders a person always wants and never wants, over the same JMAP connection it uses for mail. Nixt Mail uses it, and any JMAP client may. What the list does on a Nixt Server is described in Allowed and blocked senders.

The capability

The session lists the capability, with one property, in capabilities and in each account’s accountCapabilities for the person’s own account:

"https://nixtoffice.com/docs/server/jmap-sender-list": { "maxEntries": 1000 }

maxEntries is the most entries the list may hold. An account shared with somebody else, such as a mailbox they read as a delegate, does not offer it: a person’s list is theirs alone.

A request that uses the methods below names the capability in using, beside urn:ietf:params:jmap:core.

The SenderList object

Each account has exactly one list, which always exists and starts empty. Like VacationResponse, its id is singleton.

A SenderEntry has:

An entry may not name an address or domain of the person’s own organisation: mail between colleagues is the organisation’s to control. Networks cannot be listed here.

SenderList/get

The standard /get method (RFC 8620 §5.1). ids may be null or ["singleton"]; any other id is in notFound. The state is the list’s own version, which only a save changes: mail arriving never moves it.

[["SenderList/get", { "accountId": "A1", "ids": null }, "0"]]

[["SenderList/get", {
  "accountId": "A1",
  "state": "4",
  "list": [{
    "id": "singleton",
    "entries": [
      { "choice": "block", "who": "spammer.example", "note": "Every week" },
      { "choice": "allow", "who": "partner.example", "note": "" }
    ]
  }],
  "notFound": []
}, "0"]]

SenderList/set

The standard /set method (RFC 8620 §5.3), with these rules:

• Only an update of singleton is allowed. Creating or destroying it is refused with the error type singleton.
• The update sets entries, the whole list at once. Any other property is refused with invalidProperties.
• Give ifInState to save only if nobody else has changed the list since you read it, such as another of the person’s devices. Otherwise the request fails with stateMismatch.
• An entry the server will not keep is refused with invalidProperties at entries, with a description saying why. That covers too many entries, or an address or domain of the organisation’s own.

[["SenderList/set", {
  "accountId": "A1",
  "ifInState": "4",
  "update": {
    "singleton": {
      "entries": [
        { "choice": "block", "who": "spammer.example", "note": "Every week" }
      ]
    }
  }
}, "0"]]

The answer carries oldState and newState, and updated has singleton when the list was saved.