MIR-8: Folders API

Message Folders API operations

Abstract

Folders API is able to communicate to manage masage folders on the server side:

• list all folders with read/unread messages
• delete a folder
• create new folder

Motivation

Enables users to organize their messages.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Folder MUST have an id and name.

TotalMessages and Unread Messages are RECOMMENDED.

type Folder struct {
	ID             string `json:"id"`                       // id of the folder
	Name           string `json:"name" validate:"required"` // name is required
	TotalMessages  int64  `json:"totalMessages"`            // total number of messages in the folder
	UnreadMessages int64  `json:"unreadMessages"`           // total number of unread messages in the folder
}

Operations

Create new folder

RECOMMENDED URL path for REST API: POST https://{path}/folder

{
  "Name": "My folder"
}

List all folders

RECOMMENDED URL path for REST API: GET https://{path}/folder

Example JSON response:

[
  {
    "id": "9m4e2mr0ui3e8a215n4g",
    "name": "Trusted",
    "totalMessages": 541344,
    "unreadMessages": 1
  },
  {
    "id": "9m4e2mr0ui3e8a3ww6n3g",
    "name": "Good Reads",
    "totalMessages": 1000,
    "unreadMessages": 10
  }
]

Update folder name

RECOMMENDED URL path for REST API: PUT https://{path}/folder

{
  "ID": "9m4e2mr0ui3e8a215n4g",
  "Name": "new name"
}

Rationale

Folders are for organizing user messages.

Security Considerations

Folders specifically belong the a single user. All API communication must be conducted over TLS 1.2 or newer protocol.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Igor Rendulic, "MIR-8: Folders API [DRAFT]," Mailio Improvement Proposals, no. 8, July 2022. [Online serial]. Available: https://mirs.mail.io/MIRS/mir-8.