API & Developer Manual

% PEPS API Guide % MLstate

This document is a preliminary version of the PEPS public API.

PEPS offers numerous APIs, and is gaining APIs quickly. This document details the endpoints and their detailed use. A sample python script demonstrates the practical use of the PEPS API.

Login

OAuth connection

To start an OAuth connection with a pair of consumer key and secret, it suffices to declare them in the configuration file config.py:

# OAuth
consumer_key = '123'
consumer_secret = '456'

The command webmail = WebmailApi() will initiate the connection using these parameters.

Direct login

To switch to direct login, the consumer_key must be assigned to the empty string in config.py. The credentials are prompted during the construction of the WebmailApi object.

API

Messages

def message_list(self, maxResults=None, pageToken=None, labelId='INBOX')

Fetch a list of user messages.

• labelId specifies the source box.
• maxResults limits the number of results (defaults to 50).
• pageToken: by default, only the most recent messages are fetched. The pageToken allows to skip a number of messages (it is typically a message identifier). If successful, the response will be a json value of the form:

{
  'messages': [{'id': string}],
  'nextPageToken': string,
  'resultSizeEstimate': integer
}

---

def message_modify(self, id, change)

Modify the flags of a single message.

• id specifies the message.
• change changes to apply to the message. The changes must be of the following form, wherein the label ids correspond to folder identifiers.

{
  'addLabelIds': [string],
  'removeLabelIds': [string]
}

If successful, the response will be a json value of type

{
  'id': string,
  'labelIds': [string]
}

---

def message_attachment(self, id, attachmentId)

Return a specific message attachment.

• id specifies the message.
• attachmentId attachment's identifier. If successful, the response will be a json value of the form:

{
  'data': bytes,
  'size': integer,
  'attachmentId': string
}

The attachment metadata is returned in the message multipart (message_get endpoint), including the fields

{
  'filename': string,
  'mimeType': string
}

Tags

For more transparency, the type tags has been defined which include both folders and labels. Tag methods have been grouped together in the API path `/users/me/tags.. following the same pattern as folder methods, with notable differences:

def tag_get(self, id, attachmentId)

Return a specific tag.

• id specifies the message.

If successful, the response will be a json value of type:

{ 'label': {'id': integer, 'name': string, 'category': category} }

if the tag corresponds to a label, and

{
  'folder':
  {
    'id': string,
    'name': string,
    'content':
    {
      'count': integer,
      'starred': integer,
      'unread': integer,
      'new': integer
    }
  }
}

otherwise. Label categories should be {'personal': {}} or {'shared': {}}.

---

def tag_get(self)

List personal labels and folders. The response will be a json value with two fields:

{
  'folders': [folder],
  'labels': [label]
}

The types folder and label match those used in tag_get.

---

def tag_create(self, data)

def tag_update(self, id, data)

Create or update a tag. The data parameters used are identical for both methods.

• id identifier of the tag to be modified
• data update parameters

In case the update is successful, the id of the tag is returned as {id: string} in the response body. The data parameters must be of the form:

{
  'label':
  {
    'name': string,
    'description': string,
    'category': category
  }
}

for labels, and

{ 'folder': {'name': string} }

for folders.

Files

def file_get(self, path)

Fetch the contents of a resource (file or directory).

• path the path identifying the resource If successful, the response will include the file contents (or the empty string if a directory), as well as the resource metadata in the X-Webmail-Metadata header:

{
  'id': string,
  'hash': bytes, // Not implemented yet.
  'name': string,
  'path': string,
  'is_dir': boolean,
  'modified': integer, // Date of the last modification.
  'icon': string,
  // File only.
  'rev': string,
  'thumb_exists': boolean,
  'mime_type': string,
  'size': integer, // Human readable.
  'bytes': integer,
  'class': string, // New in webmail; file security class.
  // Directory only.
  'contents': [..] // List the elements inside a directory (metadata)
}

Reasons for failure can be:

• File not found, which causes a 404 error
• Unauthorised 401 (user does not have access to this resource)

---

def file_metadata(self, path, list=False, file_limit=10000)

Fetch a resource metadata.

• path path to the resource
• list list folder contents
• file_limit not used

The metadata is returned in the response body.

Encryption

PEPS uses end-to-end encryption. Therefore, API clients should implement encryption on their own. Since implementing cryptography is hard, we recommend that you contact MLstate to get in touch with us to learn more about encryption APIs and how to use them.

List of endpoints

OAuth protocol

GET    "/oauth/request_token" .*
GET    "/oauth/authorize" .*
POST   "/oauth/access_token" .*
GET    "/oauth/gnameadmin" .*
GET    "/oauth/logout" .*

Direct login

POST   "/login" .*

Drafts

Create: POST   "/users/" uid=user_id "/drafts"(.)
Delete: DELETE "/users/" uid=user_id "/drafts/" mid=message_id
Get: GET    "/users/" uid=user_id "/drafts/" mid=message_id
List: GET    "/users/" uid=user_id "/drafts": Http.Json.not_found({error
Update: PUT    "/users/" uid=user_id "/drafts/" mid=message_id
Send: POST   "/users/" uid=user_id "/drafts/send"
List: GET    "/users/" uid=user_id "/history" ("?" .*)?

Folders

Create: POST   "/users/" uid=user_id "/folders" ("?" .*)?
Delete: DELETE "/users/" uid=user_id "/folders/" fid=folder_id ("?" .*)?
List: GET    "/users/" uid=user_id "/folders" ("?" .*)?
Update: PUT    "/users/" uid=user_id "/folders/" fid=folder_id ("?" .*)?
Get: GET    "/users/" uid=user_id "/folders/" fid=folder_id ("?" .*)?
Patch: PATCH  "/users/" uid=user_id "/folders/" fid=folder_id ("?" .*)?

Tags: a mix of folder and label operations

Get: GET    "/users/" uid=user_id "/tags/" id=string_id ("?" .*)?
List: GET    "/users/" uid=user_id "/tags" ("?" .*)?
Delete: DELETE "/users/" uid=user_id "/tags/" id=string_id ("?" .*)?
Create: POST   "/users/" uid=user_id "/tags" ("?" .*)?
Update: PUT    "/users/" uid=user_id "/tags/" id=string_id ("?" .*)?

Messages

Delete: DELETE "/users/" uid=user_id "/messages/" mid=message_id ("?" .*)?
Get: GET    "/users/" uid=user_id "/messages/" mid=message_id ("?" .*)?
List: GET    "/users/" uid=user_id "/messages" ("?" .*)?
Modify: POST   "/users/" uid=user_id "/messages/" mid=message_id "/modify" ("?" .*)?
Send: POST   "/users/" uid=user_id "/messages/send" ("?" .*)?
Trash: POST   "/users/" uid=user_id "/messages/" mid=message_id "/trash" ("?" .*)?
Untrash: POST   "/users/" uid=user_id "/messages/" mid=message_id "/untrash" ("?" .*)?

Attachments

GET    "/users/" uid=user_id "/messages/" mid=message_id "/attachments/" fid=file_id ("?" .*)?

Users

History: GET    "/users/history" ("?" .*)?
Get: GET    "/users/" uid=user_id ("?" .*)?
Create new users: POST   "/users" ("?" .*)?
Update existing users (except for teams): PUT    "/users/" uid=user_id ("?" .*)?
List: GET    "/users" ("?" .*)?
Delete: DELETE "/users/" uid=user_id ("?" .*)?
Update user teams: PUT    "/users/" uid=user_id "/move" ("?" .*)?

Teams

History: GET    "/teams/history" ("?" .*)?
Get: GET    "/teams/" tid=team_id ("?" .*)?
Create: POST   "/teams" ("?" .*)?
Update: PUT    "/teams/" tid=team_id  ("?" .*)?
Delete: DELETE "/teams/" tid=team_id ("?" .*)?
List: GET    "/teams" ("?" .*)?

Files

Metadata: GET    "/files/metadata/" path=((!"?" .)*) ("?" .*)?
Folder creation: POST   "/fileops/create_folder" ("?" .*)?
File and directory copy: POST   "/fileops/copy" ("?" .*)?
Deletion: POST   "/fileops/delete" ("?" .*)?
Move: POST   "/fileops/move" ("?" .*)?

Notifications

GET    "/notify/" user=user_id ("?" .*)?