server/protocols/jmap-draft/doc/specs/spec/account.mdwn

## Accounts
<aside class="warning">
Not implemented
</aside>

A single login may provide access to multiple accounts, for example if another user is sharing their mail with the logged in user.

All data belongs to an account. With the exception of a few explicit operations to copy data between accounts, all methods take an *accountId* argument that specifies on which account the operations are to take place. This argument is always optional; if not specified, the primary account is used. All ids (other than Account ids of course) are only unique within their account.

An **Account** object has the following properties:

- **id**: `String`
  The id of the account. This property is immutable.
- **name**: `String`
  A user-friendly string to show when presenting content from this account. e.g. the email address of the account.
- **isPrimary**: `Boolean`
  This MUST be true for exactly one of the accounts returned.
- **capabilities**: `AccountCapabilities`
  An object describing general capabilities of this server.
- **mail**: `MailCapabilities|null`
  If `null`, this account does not support mail, and any use of the mail-related methods with this account will result in an `accountNoMail` error. Otherwise, it will be an object describing certain capabilities of the mail system.
- **contacts**: `ContactsCapabilities|null`
  If `null`, this account does not support contacts, and any use of the contacts-related methods with this account will result in an `accountNoContacts` error. Otherwise, it will be an object describing certain capabilities of the contacts system.
- **calendars**: `CalendarsCapabilities|null`
  If `null`, this account does not support calendars, and any use of the calendar-related methods with this account will result in an `accountNoCalendars` error. Otherwise, it will be an object describing certain capabilities of the calendars system.

An **AccountCapabilities** object has the following properties:

- **maxSizeUpload**: `Number`
  The maximum file size, in bytes, that the server will accept for a single file upload (for any purpose).

A **MailCapabilities** object has the following properties:

- **isReadOnly**: `Boolean`
  True if the user has read-only access to the mail in this account. The user may not use the `set`-type mail methods with this account.
- **maxSizeMessageAttachments**: `Number`
  The maximum total size of attachments, in bytes, allowed for messages. A server MAY still reject messages with a lower attachment size total (for example, if the body includes several megabytes of text, causing the size of the encoded MIME structure to be over some server-defined limit).
- **canDelaySend**: `Boolean`
  Does the server support inserting a message into the outbox to be sent later at a user-specified time?
- **messageListSortOptions**: `String[]`
  A list of all the message properties the server supports for sorting by. This MAY include properties the client does not recognise (for example custom properties specified in the vendor extension). Clients MUST just ignore any unknown properties in the list.

A **ContactsCapabilities** object has the following properties:

- **isReadOnly**: `Boolean`
  True if the user has read-only access to the contacts in this account. The user may not use the `set`-type contacts methods with this account.

A **CalendarsCapabilities** object has the following properties:

- **isReadOnly**: `Boolean`
  True if the user has read-only access to the calendars in this account. The user may not use the `set`-type calendar methods with this account.

The AccountCapabilities, MailCapabilities, ContactsCapabilities and CalendarsCapabilities objects MAY also contain one or more properties prefixed with "vnd-" + a name that uniquely identifies the vendor. For example `"vnd-com.fastmail"`. The value type for these properties is undefined. These properties allow vendors to be able to inform their own clients of custom capabilities. Unknown properties of this form MUST be ignored by clients.

### getAccounts

To fetch the complete list of accounts to which the user has access, make a call to `getAccounts`. It takes a sole, optional argument:

- **sinceState**: `String|null`
  This is the `state` string from a previous call to *getAccounts*.

The response to *getAccounts* is called *accounts*. It has the following arguments:

- **state**: `String`
   A string representing the state on the server for **all** the data contained within the Account objects. If the data changes, this string will change.
- **list**: `Account[]|null`
  An array of all Account objects. If *sinceState* was supplied and it is identical to the current state, this property is `null`.

The following errors may be returned instead of the `accounts` response:

`invalidArguments`: Returned if the `sinceState` argument is included and has the wrong type.

Example of a successful request:

    ["getAccounts", {}, "#0"]

and response:

    [ "accounts", {
      "state": "f6a7e214",
      "list": [
        {
          "id": "6asf5",
          "name": "user@example.com",
          "isPrimary": true,
          "capabilities": {
            maxSizeUpload: 1000000000
          },
          "mail": {
            "isReadOnly": false,
            "maxSizeMessageAttachments": 50000000,
            "canDelaySend": true,
            "messageListSortOptions": [
              "id", "date", "subject", "from", "to",
              "isUnread", "isPinned", "threadUnread", "threadPinned"
            ],
          },
          "contacts": {
            "isReadOnly": false
          },
          "calendars": {
            "isReadOnly": false
          }
        },
        {
          "id": "e12e1a",
          "name": "shared.user@example.com",
          "isPrimary": false,
          "capabilities": {
            maxSizeUpload: 0
          },
          "mail": null,
          "contacts": null,
          "calendars": {
            "isReadOnly": true
          }
        }
      ]
    }, "#0" ]