Label

ElasticInbox uses labels as a replacement for the classic mailbox folders. Each label has ID, name and custom attributes. Nested labels (like subfolders) are also supported.

Each label can have a set of custom attributes such as color, order, icon, etc.

Each account has a set of reserved labels which are created automatically when account initiated.

For more information please refer to Labels and Markers wiki page.

Get all labels

Returns all labels, their IDs, and optionally metadata (number of total and unread messages in the label).

GET /rest/v2/:domain/:user/mailbox/

Parameters

metadata
Optional boolean - Returns total and unread message count. Also returns total bytes for the all label which is effectively mailbox size. Default value is false.

Response without metadata

Status: 200 OK
{
  "0": "all",
  "1": "inbox",
  "2": "drafts",
  "3": "sent",
  "4": "trash",
  "5": "spam",
  "6": "starred",
  "7": "important",
  "8": "notifications",
  "9": "attachments",
  "10": "pop3",
  "340": "MyLabel",
  "1334": "MyLabel^NestedLabel"
}

Response with metadata

Status: 200 OK
{
  "0": {
    "name": "all",
    "size": 2193085,
    "total": 230,
    "unread": 13
  },
  "1": {
    "name": "inbox",
    "total": 190,
    "unread": 12
  },
  "2": {
    "name": "drafts",
    "total": 3,
    "unread": 0
  },
  "1232": {
    "name": "MyBlueLabel",
    "total": 8,
    "unread": 2,
    "attributes": {
      "order": "6",
      "color": "blue"
    }
  },
  "...": "..."
}

Example request

% curl -XGET "http://host:8181/rest/v2/domain.tld/user/mailbox?metadata=true"

Add label

Each account can have custom labels (similar to conventional folders). Unique label ID is automatically generated for each new label. Each account can have up to 10.000 labels.

Note: Label names are case insensitive, but will preserve letter cases.

POST /rest/v2/:domain/:user/mailbox/label

Parameters

name
Required string - New label name. Should not contain ^ character.

Input

Label name can also be specified in the request body. Custom attributes should be specified in the request body.

Note: Request content type should be application/json

Note: : character is not allowed in attribute names

{
  "name": "MyStarLabel",
  "attributes": {
    "icon": "star",
    "color": "yellow",
    "...": "..."
  }
}

Response

Status: 201 Created
Location: http://host:8181/rest/v2/domain.tld/user/mailbox/label/306
{
  "id": 306
}

Response if label name disallowed or reserved

Status: 400 Bad Request
{
  "message": "Error message"
}

Response if label with the given name already exists

Status: 409 Conflict
{
  "message": "Error message"
}

Example request

% curl -XPOST \
  "http://host:8181/rest/v2/domain.tld/user/mailbox/label" \
   -d "{\"name\" : \"MyStarLabel\", \"attributes\" : { \"color\" : \"yellow\" } }" \
   -H "Content-Type: application/json"

Update label

Rename label, update and remove custom attributes. To remove custom attribute set it to empty string or null.

PUT /rest/v2/:domain/:user/mailbox/label/:id

Parameters

name
Required string - New label name. May not contain ^ character.

Input

Note: Request content type should be application/json

Note: : character is not allowed in attribute names

{
  "name": "RenameMyStar",
  "attributes": {
    "icon": "yellow-star",
    "color": ""
  }
}

Response

Status: 204 No Content

Response if label with the given name already exists

Status: 409 Conflict
{
  "message": "Error message"
}

Example request

% curl -XPUT \
  "http://host:8181/rest/v2/domain.tld/user/mailbox/label/306" \
   -d "{\"name\" : \"RenameMyStar\", \"attributes\" : { \"color\" : \"\" } }" \
   -H "Content-Type: application/json"

Delete label

This operation deletes label and removes label from all associated messages.

DELETE /rest/v2/:domain/:user/mailbox/label/:id

Response

Status: 204 No Content

Response if label is reserved

Status: 400 Bad Request
{
  "message": "Error message"
}

Example request

% curl -XDELETE "http://host:8181/rest/v2/domain.tld/user/mailbox/label/306"