API & Developer Manual

WIP, this section will be improved soon

A sample python script demonstrates the use of the PEPS API which will be fully documented here.

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.