Magma JSON Interface

Description: This document summarizes the JSON interface for the Magma email platform.

Version: 0.6.5

Last Updated: Tue, 07 Jun 2016 04:00:37 -0500

Assumptions:

Document MO:

Method Tester

Response time
none
Response size
none

Table of Contents

back to contents

Gets advertisement and fun facts for loading screen and ad banner for messages.

Request Params

["context"] - where the ad will be displayed

  1. "loading"
  2. "messages" (def)

Example Request

{
    "id": 1,
    "method": "ad",
    "params": {
        "context": "loading"
    }
}

Response Params

"ad"

["fact"]

Example Response

[{
    "result": {
        "ad": {
            "href": "/advertisement.html",
            "title": "Loading Ad",
            "img": {
                "src": "http://placehold.it/300x250",
                "alt": "Loading Ad"
            }
        },
        "fact": {
            "text": [
                "Most elephants weigh less than the tongue of a blue whale."
            ]
        }
    }
}, {
    "result": {
        "ad": {
            "href": "/advertisement.html",
            "title": "Wide Advertisement",
            "img": {
                "src": "http://placehold.it/728x90",
                "alt": "Wide Advertisement"
            }
        }
    }
}, {
    "result": {
        "ad": {
            "href": "/text-ad.html",
            "title": "Text Ad",
            "text": "This is a text ad"
        }
    }
}, {
    "error": true
}]

Method: alert.acknowledge

back to contents

The web client will use this method to acknowledge receipt of one or more alerts.

Request Params

["alertIDs"] - an array of alert ids that the client is acknowledging that it has received

Example Request

{
    "id": 2,
    "method": "alert.acknowledge",
    "params": {
        "alertIDs": [1,2]
    }
}

Example Response

{
    "jsonrpc": "2.0",
    "result": {
        "alert.acknowledge": "success"
    },
    "id": 3
}

Method: alert.list

back to contents

The client will send an alert.list request to retrieve a list of all unacknowledged alert messages.

Response Params

"alertID" - the ID of the alert message

"type"

  1. "alert" - (def)
  2. "warning"

"message"

"utc"

Example Response

[{
    "result": [{
        "alertID": 1,
        "type": "alert",
        "message": "It's a trap!",
        "date": "1029381092830"
    }, {
        "alertID": 2,
        "type": "warning",
        "message": "Your subscription will expire soon.",
        "date": "12093810293801"
    }]
}, {
    "result": true
}, {
    "error": true
}]

Method: aliases

back to contents

Gets a list of user aliases to populate the From field dropdown in a new message composition.

Response Params

"email" - the email address corresponding to this alias

"name" - the display name of this alias

["def"] - indicates which to display by default, and is only set if true (default keyword reserved by javascript)

Example Response

[{
    "result": [{
        "email": "peter@lavabit.com",
        "name": "Peter"
    }, {
        "email": "work@lavabit.com",
        "name": "Work",
        "def": true
    }, {
        "email": "peter@pan.com",
        "name": "Website"
    }, {
        "email": "email@example.com",
        "name": "Test Email"
    }]
}, {
    "error": true
}]

Method: attachments.add

back to contents

Sent by a user that wants to attach a file to a composition. Note that a separate non-ajax upload must be made to actually affix the attachment data (%CAMELHOST%/portal/camel/attach/[compid]/[attachid]) where [compid] is the message composition ID and attachid is the attachment ID to which the file about to be uploaded will be attached.

Request Params

"composeID" - a composition ID provided by server when the user starts composing a new message

"filename" - the name of the filename to be attached to the composition

Example Request

{
    "id": 5,
    "method": "attachments.add",
    "params": {
        "composeID": 45,
        "filename": "script.js"
    }
}

Response Params

"attachmentID" - an attachment ID that will later be passed to the messages.send method

Example Response

[{
    "result": {
        "attachmentID": 34
    }
}, {
    "error": true
}]

Method: attachments.progress

back to contents

Pulls server for progress of file upload.

Request Params

"attachmentID"

Example Request

{
    "id": 6,
    "method": "attachments.progress",
    "params": {
        "attachmentID": 34
    }
}

Response Params

"progress" - 0 to 100 indicating percent complete

["size"] - in bytes

["rate"]

Example Response

[{
    "result": {
        "progress": 54
    }
}, {
    "error": true
}]

Method: attachments.remove

back to contents

Removes an attachment from a message composition.

Request Params

"composeID" - the composition ID containing the attachment

"attachmentID" - the ID of the attachment to be removed

Example Request

{
    "id": 7,
    "method": "attachments.remove",
    "params": {
	"composeID": 1,
        "attachmentID": 34
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: auth

back to contents

Sent when user submits login form. In this case, the example requests correspond to the errors respectively.

Request Params

"username"

"password"

Example Request

{
    "id": 8,
    "method": "auth",
    "params": {
        "username": "magma",
        "password": "test"
    }
}

Response Params

"auth" - string 1. "success" 1. "failed" 1. "locked"

"session" - sessionID sent when successfully authenticated

"message" - error message

Example Response

[{
    "result": {
        "auth": "success",
        "session": ""
    }
}, {
    "result": {
        "auth": "failed",
        "message": "The username and password provided are incorrect, please try again."
    }
}, {
    "result": {
        "auth": "locked",
        "message": "Your account is locked due to abuse."
    }
}]

Method: config.load

back to contents

A way for the web client to retrieve the user's complete configuration collection.

Response Params

fill me in: result is a free-form object

Example Response

No example response

Method: contacts.add

back to contents

Add an entry to a contacts folder.

Request Params

"folderID" - the ID of the contacts folder, which could be returned by the folders.list method

["contact"]

Example Request

{
	"id":4,
	"method":"contacts.add",
	"params":{
		"folderID":7,
		"contact":{
			"name":"Jenna", 
			"email":"jenna@jameson.com"
		}
	}
}

Response Params

"contactID" - the ID of the newly created contact entry

Example Response

[{
    "result": {
        "contactID": 88
    }
}, {
    "error": true
}]

Method: contacts.edit

back to contents

Change a contact's info. This method has several parameters that are optional since it only sends the updated fields. The response sends back all the fields that are set on the server.

Request Params

"contactID"

["name"] - full name of contact

["email"]

["chat"] - IM/XMPP/IRC handles

["phone"]

["address"]

Example Request

{
	"id":4,
	"method":"contacts.edit",
	"params":{
		"folderID":7,
		"contactID": 1,
		"contact":{
			"phone": "2145551212"
		}
	}
}

Response Params

"contactID"

["name"] - full name of contact

["email"]

["chat"] - IM/XMPP/IRC handles

["phone"]

["address"]

Example Response

[{
    "result": {
        "name": "Peter Pan",
        "email": {
            "primary": "peter@lavabit.com",
            "alternate-1": "peter@pan.com"
        },
        "chat": {
            "yahoo": "pp@yahoo.com",
            "live": "pp@hotmail.com",
            "aim": "peanutbutter",
            "google": "pp@gmail.com"
        },
        "phone": {
            "home": "123-456-7890",
            "work": "123-456-7890",
            "mobile": "123-456-7890",
            "address": ["1234 Lost Way", "Neverland Isl"]
        }
    }
}, {
    "error": true
}]

Method: contacts.list

back to contents

Summarize contact info in a table.

Request Params

"folderID"

Example Request

{
    "id": 9,
    "method": "contacts.list",
    "params": {
        "folderID": 3
    }
}

Response Params

"contactID"

"name" - contact's full name

"email"

["company"]

["img"] - avatar

Example Response

[{
    "result": [{
        "contactID": 45,
        "name": "John Resig",
        "email": "jr@mozilla.org",
        "company": "Mozilla",
        "img": {
            "src": "http://www.gravatar.com/avatar/00000000000000000000000000000000?s=32&d=mm&f=y",
            "alt": "Avatar"
        }
    }, {
        "contactID": 48,
        "name": "Linus Torvalds",
        "email": "lt@kernel.org",
        "company": "Linux"
    }, {
        "contactID": 53,
        "name": "Douglas Crockford",
        "email": "dc@yahoo.com",
        "company": "Yahoo",
        "img": {
            "src": "http://www.gravatar.com/avatar/00000000000000000000000000000000?s=32&d=mm&f=y",
            "alt": "Avatar"
        }
    }, {
        "contactID": 58,
        "name": "Paul Graham",
        "email": "pg@ycombinator.com",
        "company": "Y Combinator",
        "img": {
            "src": "http://www.gravatar.com/avatar/00000000000000000000000000000000?s=32&d=mm&f=y",
            "alt": "Avatar"
        }
    }, {
        "contactID": 64,
        "name": "John Paul",
        "email": "jp@morgan.com"
    }]
}, {
    "result": [{
        "contactID": 45,
        "name": "John Resig",
        "email": "jr@mozilla.org",
        "company": "Mozilla",
    }, {
        "contactID": 48,
        "name": "Linus Torvalds",
        "email": "lt@kernel.org",
        "company": "Linux"
    }, {
        "contactID": 53,
        "name": "Douglas Crockford",
        "email": "dc@yahoo.com",
        "company": "Yahoo",
    }, {
        "contactID": 58,
        "name": "Paul Graham",
        "email": "pg@ycombinator.com",
        "company": "Y Combinator",
    }, {
        "contactID": 64,
        "name": "John Paul",
        "email": "jp@morgan.com"
    }]
}, {
    "error": true
}]

Method: contacts.load

back to contents

Load the contact info for a particular contact.

Request Params

"contactID"

"folderID"

Example Request

{
    "id": 10,
    "method": "contacts.load",
    "params": {
        "contactID": 88
        "folderID": 26
    }
}

Response Params

"name"

"email"

["chat"]

["contact"]

Example Response

[{
    "result": {
        "name": "Douglas Crockford",
        "email": {
            "primary": "dougcrock@lavabit.com",
            "alternate1": "dc@crockford.com"
        },
        "chat": {
            "yahoo": "crockford@yahoo.com",
            "aim": "thejsguy",
            "google": "crockford@gmail.com"
        },
        "contact": {
            "home": "123-456-7890",
            "work": "123-456-7890",
            "mobile": "123-456-7890",
            "address": "1234 Yahoo<br \/>Sunnyvale, CA 12345 "
        }
    }
}, {
    "error": true
}]

Method: contacts.remove

back to contents

Removes the specified contact.

Request Params

"contactID"

Example Request

{
    "id": 12,
    "method": "contacts.remove",
    "params": {
    	"folderID": 1
        "contactID": 88
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: display-options

back to contents

Not implemented yet

Example Response

{
    "result": {
        "reading-pane": 2,
        "fields": ["from", "to", "subject", "date", "size"],
        "sort": {
            "field": "from",
            "order": 1
        }
    },
    "error": true
}

Method: folders.add

back to contents

Adds a folder with given name and returns folderID.

Request Params

"context" - the type of the new folder to be created; can be either "mail" or "contacts"

"name" - name of the new folder

["parentID"] - given if added folder is a child of a parent folder other than the root

Example Request

{
    "id": 13,
    "method": "folders.add",
    "params": {
        "parentID": 9,
        "name": "Bitbucket"
    }
}

Response Params

"folderID" - global folderID assigned by server

Example Response

[{
    "result": {
        "folderID": 41
    }
}, {
    "error": true
}]

Method: folders.list

back to contents

Lists the folders to be displayed in view menu.

Request Params

"context" - lets server know which folders to list

  1. "mail" - (def)
  2. "contacts"

    1. "settings"

1. "help"

Example Request

{
    "id": 14,
    "method": "folders.list",
    "params": {
        "context": "mail"
    }
}

Response Params

"folderID" - the ID of the listed folder

["parentID"] - is not provided in the response if the folder is at the root level

"name" - the name of the listed folder

Example Response

[{
    "result": [{
        "folderID": 1,
        "name": "Inbox"
    }, {
        "folderID": 5,
        "name": "Projects"
    }, {
        "folderID": 8,
        "parentID": 12,
        "name": "jQuery Plugins"
    }, {
        "folderID": 10,
        "parentID": 12,
        "name": "Tests"
    }, {
        "folderID": 11,
        "parentID": 10,
        "name": "Webmail"
    }, {
        "folderID": 15,
        "parentID": 12,
        "name": "Templates"
    }, {
        "folderID": 12,
        "name": "Javascript"
    }, {
        "folderID": 9,
        "parentID": 8,
        "name": "Querios"
    }]
}, {
    "result": [{
        "folderID": 200,
        "name": "All"
    }, {
        "folderID": 201,
        "name": "People"
    }, {
        "folderID": 202,
        "name": "Business"
    }, {
        "folderID": 203,
        "name": "Collected"
    }, {
        "folderID": 204,
        "name": "Work"
    }, {
        "folderID": 205,
        "name": "Personal"
    }, {
        "folderID": 206,
        "parentID": 205,
        "name": "Family"
    }, {
        "folderID": 207,
        "parentID": 205,
        "name": "Friends"
    }, {
        "folderID": 999,
        "name": "No Gravatars"
    }]
}, {
    "result": [{
        "folderID": 100,
        "name": "Identity"
    }, {
        "folderID": 101,
        "name": "Mail Settings"
    }, {
        "folderID": 102,
        "name": "Portal Settings"
    }, {
        "folderID": 103,
        "name": "Account Upgrades"
    }, {
        "folderID": 104,
        "name": "Password"
    }]
}, {
    "result": [{
        "folderID": 400,
        "name": "Statistics"
    }, {
        "folderID": 401,
        "name": "Security"
    }, {
        "folderID": 402,
        "name": "Contacts"
    }, {
        "folderID": 403,
        "name": "Mail"
    }]
}, {
    "result": [{
        "folderID": 500,
        "name": "Help Category"
    }, {
        "folderID": 501,
        "name": "Help Category"
    }, {
        "folderID": 502,
        "name": "Help Category"
    }]
}, {
    "error": true
}]

Method: folders.remove

back to contents

Removes the folder.

Request Params

"folderID"

Example Request

{
    "id": 16,
    "method": "folders.remove",
    "params": {
        "folderID": 30
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: folders.rename

back to contents

Rename the specified folder.

Request Params

"context" - lets server know which type of folder will be renamed

  1. "mail" - (def)
  2. "contacts"
  3. "settings"
  4. "help"

"folderID" - the id of the folder to be renamed

"name" - the new name of the folder

Example Request

{
    "id": 17,
    "method": "folders.rename",
    "params": {
        "folderID": 30,
        "name": "New Name"
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: help.page

back to contents

Get html for wiki style help pages.

Request Params

"topicID"

Example Request


Response Params

Example Response

[{
    "jsonrpc": "2.0",
    "result": "<h2>Help</h2><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ipsum orci, dictum quis vestibulum id, lobortis eget nibh. Cras diam ante, adipiscing vel elementum ut, fringilla non magna. Nunc eu metus libero, at condimentum dolor. Donec sit amet est quis eros condimentum lobortis et ut ipsum. Suspendisse diam nisl, blandit vitae lobortis vitae, fermentum ut est. Sed placerat nisl eu neque auctor non tempor urna mattis. Aenean convallis nibh eros. Nunc egestas scelerisque urna, non congue erat iaculis in. Donec consectetur luctus fringilla. In in ligula eu libero mattis ornare. Curabitur iaculis porta leo eu consectetur. Nulla lacus tortor, vehicula non pellentesque sed, tincidunt at ante. Mauris rhoncus rhoncus nisl eget rhoncus. Etiam consequat nunc ut enim bibendum vitae porta dui laoreet. Aenean placerat nisi ac urna dignissim dignissim in ut velit.</p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ipsum orci, dictum quis vestibulum id, lobortis eget nibh. Cras diam ante, adipiscing vel elementum ut, fringilla non magna. Nunc eu metus libero, at condimentum dolor. Donec sit amet est quis eros condimentum lobortis et ut ipsum. Suspendisse diam nisl, blandit vitae lobortis vitae, fermentum ut est. Sed placerat nisl eu neque auctor non tempor urna mattis. Aenean convallis nibh eros. Nunc egestas scelerisque urna, non congue erat iaculis in. Donec consectetur luctus fringilla. In in ligula eu libero mattis ornare. Curabitur iaculis porta leo eu consectetur. Nulla lacus tortor, vehicula non pellentesque sed, tincidunt at ante. Mauris rhoncus rhoncus nisl eget rhoncus. Etiam consequat nunc ut enim bibendum vitae porta dui laoreet. Aenean placerat nisi ac urna dignissim dignissim in ut velit.</p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ipsum orci, dictum quis vestibulum id, lobortis eget nibh. Cras diam ante, adipiscing vel elementum ut, fringilla non magna. Nunc eu metus libero, at condimentum dolor. Donec sit amet est quis eros condimentum lobortis et ut ipsum. Suspendisse diam nisl, blandit vitae lobortis vitae, fermentum ut est. Sed placerat nisl eu neque auctor non tempor urna mattis. Aenean convallis nibh eros. Nunc egestas scelerisque urna, non congue erat iaculis in. Donec consectetur luctus fringilla. In in ligula eu libero mattis ornare. Curabitur iaculis porta leo eu consectetur. Nulla lacus tortor, vehicula non pellentesque sed, tincidunt at ante. Mauris rhoncus rhoncus nisl eget rhoncus. Etiam consequat nunc ut enim bibendum vitae porta dui laoreet. Aenean placerat nisi ac urna dignissim dignissim in ut velit.</p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ipsum orci, dictum quis vestibulum id, lobortis eget nibh. Cras diam ante, adipiscing vel elementum ut, fringilla non magna. Nunc eu metus libero, at condimentum dolor. Donec sit amet est quis eros condimentum lobortis et ut ipsum. Suspendisse diam nisl, blandit vitae lobortis vitae, fermentum ut est. Sed placerat nisl eu neque auctor non tempor urna mattis. Aenean convallis nibh eros. Nunc egestas scelerisque urna, non congue erat iaculis in. Donec consectetur luctus fringilla. In in ligula eu libero mattis ornare. Curabitur iaculis porta leo eu consectetur. Nulla lacus tortor, vehicula non pellentesque sed, tincidunt at ante. Mauris rhoncus rhoncus nisl eget rhoncus. Etiam consequat nunc ut enim bibendum vitae porta dui laoreet. Aenean placerat nisi ac urna dignissim dignissim in ut velit.</p><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ipsum orci, dictum quis vestibulum id, lobortis eget nibh. Cras diam ante, adipiscing vel elementum ut, fringilla non magna. Nunc eu metus libero, at condimentum dolor. Donec sit amet est quis eros condimentum lobortis et ut ipsum. Suspendisse diam nisl, blandit vitae lobortis vitae, fermentum ut est. Sed placerat nisl eu neque auctor non tempor urna mattis. Aenean convallis nibh eros. Nunc egestas scelerisque urna, non congue erat iaculis in. Donec consectetur luctus fringilla. In in ligula eu libero mattis ornare. Curabitur iaculis porta leo eu consectetur. Nulla lacus tortor, vehicula non pellentesque sed, tincidunt at ante. Mauris rhoncus rhoncus nisl eget rhoncus. Etiam consequat nunc ut enim bibendum vitae porta dui laoreet. Aenean placerat nisi ac urna dignissim dignissim in ut velit.</p>",
    "id": 100
}, {
    "error": true
}]

Method: help.topics

back to contents

List help topics for a category.

Request Params

"categoryID"

Example Request


Response Params

"topicID"

"name" - topic display name

Example Response

[{
    "jsonrpc": "2.0",
    "result": [{
        "topicID": 600,
        "name": "Help Topic"
    }, {
        "topicID": 601,
        "name": "Help Topic"
    }, {
        "topicID": 602,
        "name": "Help Topic"
    }],
    "id": 100
}, {
    "error": true
}]

Method: logs.mail

back to contents

Retrieve mail logs

Response Params

"name" - full name

"first" - first name

"last" - last name

"website"

Example Response

[{
    "result": [{
        "messageID": 100,
        "queue": 1011,
        "type": "Incoming",
        "from": "Bill Shakespeare",
        "to": "Bill Gates",
        "outcome": "Delivered",
        "utc": 102032012310,
        "bytes": 1024
    }, {
        "messageID": 101,
        "queue": 1012,
        "type": "Outgoing",
        "from": "Bob Dole",
        "to": "Bob Dylan",
        "outcome": "Delayed",
        "utc": 102033422369,
        "bytes": 1232
    }, {
        "messageID": 102,
        "queue": 1013,
        "type": "Incoming",
        "from": "Bill Shakespeare",
        "to": "Bill Gates",
        "outcome": "Delivered",
        "utc": 102032012310,
        "bytes": 123145
    }, {
        "messageID": 103,
        "queue": 1014,
        "type": "Outgoing",
        "from": "Bob Dole",
        "to": "Bob Dylan",
        "outcome": "Delayed",
        "utc": 102033422369,
        "bytes": 10
    }, {
        "messageID": 104,
        "queue": 1015,
        "type": "Incoming",
        "from": "Bill Shakespeare",
        "to": "Bill Gates",
        "outcome": "Delivered",
        "utc": 102032012310,
        "bytes": 999
    }, {
        "messageID": 105,
        "queue": 1016,
        "type": "Outgoing",
        "from": "Bob Dole",
        "to": "Bob Dylan",
        "outcome": "Delayed",
        "utc": 102033422369,
        "bytes": 123
    }]
}, {
    "error": true
}]

Method: logs.security

back to contents

Retrieve security logs

Response Params

"utc" - unix time

"type" - login / logout

"severity"

"ip"

"protocol"

Example Response

[{
    "result": [{
        "utc": 10239834048,
        "type": "Login",
        "severity": "Zero",
        "ip": "0.0.0.0",
        "protocol": "Web"
    }, {
        "utc": 10238439074,
        "type": "Logout",
        "severity": "Zero",
        "ip": "0.0.0.0",
        "protocol": "Web"
    }, {
        "utc": 10239834157,
        "type": "Login",
        "severity": "Zero",
        "ip": "0.0.0.0",
        "protocol": "IMAP"
    }]
}, {
    "error": true
}]

Method: logs.statistics

back to contents

Gets account statistics.

Response Params

"account"

"username"

"storage"

"space"

"logins"

"smtp" - number of times accessed

"messages"

"received" - total received

"email"

"address"

"transfer"

"sent"

"blocked"

"spam"

Example Response

[{
    "result": {
        "account": {
            "username": "Mike",
            "name": "Mike",
            "number": 1,
            "reputation": "100%",
            "plan": "Free",
            "date": "Nov 11th, 2011"
        },
        "storage": {
            "space": 10203192038,
            "folders": 12,
            "stored": 1000303,
            "archived": 12030123213,
            "encrypted": 1200310320
        },
        "logins": {
            "smtp": 1000,
            "pop": 1000,
            "imap": 1000,
            "web": 1000
        },
        "messages": {
            "received": 1000,
            "sent": 1000
        },
        "email": {
            "address": "mike@lavabit.com"
        },
        "transfer": {
            "sent": 2,
            "received": 3
        },
        "blocked": {
            "spam": 0,
            "bounced": 0
        }
    }
}, {
    "error": true
}]

Method: messages.compose

back to contents

Sent when the user starts to compose a message. Gets the composeID from the server.

Response Params

"contactID"

Example Response

[{
    "result": { "composeID": 1 }
}, {
    "error": true
}]

Method: messages.copy

back to contents

Copy messages from one folder to another or the same folder.

Request Params

"messageIDs"

"sourceFolderID"

"targetFolderID"

Example Request

{
    "id": 19,
    "method": "messages.copy",
    "params": {
        "messageIDs": [100, 101, 102],
        "sourceFolderID": 1,
        "targetFolderID": 10
    }
}

Response Params

Each object in the response array is associated with a messageID in the request.

"sourceMessageID"

"targetMessageID"

Example Response

[{
    "result": [{
        "sourceMessageID": 1021,
        "targetMessageID": 1035
    }, {
        "sourceMessageID": 1022,
        "targetMessageID": 1036
    }]
}, {
    "error": true
}]

Method: messages.flag

back to contents

Assign various flags to a message. The flag property indicates what flag is being assigned.

Request Params

Each object in the example is a separate request.

"action"

"flags"

"messageIDs"

"folderID"

Example Request

[{
    "id": 20,
    "method": "messages.flag",
    "params": {
    	"action": "add",
    	"flags": ["junk"],
        "messageIDs": [100, 101, 102],
    	"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.flag",
    "params": {
        "action": "replace",
    	"flags": [],
        "messageIDs": [100, 101, 102],
    	"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.flag",
    "params": {
        "action": "remove",
		"flags": ["read"],
	    "messageIDs": [100, 101, 102],
		"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.flag",
    "params": {
        "action": "list",
	    "messageIDs": [100, 101, 102],
		"folderID": 1
    }
}]

Example Response

[{
	"jsonrpc":"2.0",
	"result":{
	    "maessages.flag" : "success"
	},
    "id":20
}, {
    "jsonrpc":"2.0",
    "result": {
        "messageID":1,
        "flags": ["flagged"]
    },
    "id":20
}]

Method: messages.list

back to contents

List messages of the given folder.

Request Params

"folderID"

Example Request

{
    "id": 21,
    "method": "messages.list",
    "params": {
        "folderID": 1
    }
}

Response Params

"messageID"

["attachment"]

["flags"]

"from"

"to"

"addressedTo"

"replyTo"

"returnPath"

["carbon"]

"subject"

"utc" - server utc time in seconds (unix time)

"arrivalUtc"

"snippet"

"bytes" - size in bytes

["tags"]

Example Response

[{
    "result": []
}, {
    "result": [{
        "messageID": 1024,
        "flags": ["seen", "flagged"],
        "from": "zWilliam Adama",
        "to": "Apallo",
        "addressedTo": "apallo@lavabit.com",
        "replyTo": "bill@lavabit.com",
        "returnPath": "bill@lavabit.com",
        "subject": "Pegasus",
        "utc": 1109749011,
        "arrivalUtc": 1109749011,
        "snippet": "Go the the gym softy",
        "bytes": 487479772 
    }, {
        "messageID": 1023,
        "attachment": true,
        "from": "Douglas Crockford",
        "to": "John Resig",
        "addressedTo": "jresig@lavabit.com",
        "replyTo": "dcrock@lavabit.com",
        "returnPath": "dcrock@lavabit.com",
        "carbon": "mozilla@lavabit.com",
        "subject": "jQuery cruft",
        "utc": 1266415038183,
        "arrivalUtc": 1020030,
        "snippet": "jQuery is too crufty. YUI is much leaner.",
        "bytes": 895625721,
        "tags": ["Javascript"]
    }, {
        "messageID": 1022,
        "from": "Paul Grahm",
        "to": "Douglas Crockford",
        "addressedTo": "dcrock@lavabit.com",
        "replyTo": "paulg@lavabit.com",
        "returnPath": "paulg@lavabit.com",
        "subject": "Reply: Y Combinator cruft",
        "utc": 1071564744567,
        "arrivalUtc": 1023012302,
        "snippet": "I have a startup idea. It's a startup starter...",
        "bytes": 1014127863,
        "tags": ["Yahoo", "Y Combinator", "cruft"]
    }, {
        "messageID": 1021,
        "from": "Douglas Crockford",
        "to": "David Flanagan",
        "addressedTo": "dflan@lavabit.com",
        "replyTo": "dcrock@lavabit.com",
        "returnPath": "dcrock@lavabit.com",
        "subject": "Javascript: The Definitive Guide cruft",
        "utc": 1054397333677,
        "arrivalUtc": 10023100321,
        "snippet": "You should only talk about the good parts.",
        "bytes": 839535031,
        "tags": ["Javascript"]
    }]
}, {
    "error": true
}]

Method: messages.load

back to contents

Loads message details to be viewed in reading screen or info accordian. Sections of the message can be requested in batches with an array.

Request Params

"messageID"

"section" - multiple can be requested

Example Request

{
    "id": 22,
    "method": "messages.load",
    "params": {
        "messageID": 1,
        "folderID": 1,
        "sections": ["header", "body", "attachments"]
    }
}

Response Params

["header"] - header summary

["body"]

["attachments"]

["info"] - extra message information

Example Response

[
  {
    "result": {
      "meta": {
        "messageID": 1,
        "folderID": 1,
        "flags": [

        ],
        "tags": [
          "thefuture"
        ]
      },
      "header": {
        "sender": "forwarder@example.org",
        "from": "John Resig",
        "to": "Mozilla",
        "cc": "carbon@example.org",
        "bcc": "blind@example.org",
        "returnpath": "bounces@example.org",
        "subject": "jQuery",
        "date": 1003939300349,
        "replyto": "John Resig",
        "size": 87348
      },
      "body": {
        "html": "<h1>Hi There!</h1><p>jQuery 1.5 just came out. You should use it!</p><p>John Resig</p>"
      },
      "attachments": [
        {
          "attachmentID": 59,
          "name": "Photo1.jpg",
          "size": 11039,
          "type": "image/jpeg"
        },
        {
          "attachmentID": 60,
          "name": "Photo2.jpg",
          "size": 12093,
          "type": "image/jpeg"
        },
        {
          "attachmentID": 60,
          "name": "profits.xlsx",
          "size": 59120,
          "type": "application/octet-stream"
        }
      ]
    }
  }, {
    "result": {
      "info": {
          "source": {
            "ip": "1.23.45.678",
            "dns": "dns1.email.com",
            "reputation": "Good"
          },
          "security": {
            "secure": true,
            "spf": true,
            "dkim": false
          },
          "server": {
            "utc": 1003029300349,
            "images": true,
            "warnings": "The message is spoofed! The signature it carries did not validate! "
          }
      }
    }
}]

Method: messages.move

back to contents

Move messages from one folder to another. Cannot be the same folder.

Request Params

"messageIDs"

"folderID"

Example Request

{
    "id": 23,
    "method": "messages.move",
    "params": {
        "messageIDs": [100, 101, 102],
        "sourceFolderID": 1,
        "targetFolderID": 10
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: messages.remove

back to contents

Move messages from one folder to another. Cannot be the same folder.

Request Params

"messageIDs"

Example Request

{
    "id": 24,
    "method": "messages.remove",
    "params": {
    	"folderID": 1,
        "messageIDs": [100, 110, 120]
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: messages.send

back to contents

Send a composed message and all of its associated attachments.

Request Params

"composeID" - the ID of the composition, as returned by the messages.compose method

"from" - the email address of the sender

["to"] - an array of at least one or more email recipients

["cc"] - an array of CC: recipients, which may optionally be left empty

["bcc"] - an array of BCC: recipients, which may optionally be left empty

["subject"] - the email subject line; not sent if empty - user warned before sent

["priority"] -

  1. "low"
  2. "normal" - (def)
  3. "high"

["body"] - the message body; not sent if empty - user warned before sent (at least html OR text must be specified)

  1. "text" - the plain text version of the email message body
    • string
  2. "html" - the html version of the email message body
    • string

Example Request

{
    "id": 25,
    "method": "messages.send",
    "params": {
        "composeID": 0,
        "from": "Douglas Crockford <dc@yahoo.com>",
        "to": [ "Linus Torvalds <lt@kernel.org>" ],
        "cc": [ ],
        "bcc": [ ],
        "subject": "Kernel cruft",
        "priority": "normal",
        "attachments": [0, 1, 3],
        "body": {
            "text": "Linux Cruft\nSplit Linux into specialized kernels to clean up some cruft!",
            "html": "<h1>Linux Cruft</h1><p>Split Linux into specialized kernels to clean up some cruft!</p><p>DC</p>"
        }
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: messages.tag

back to contents

Assign tags to messages.

Request Params

"messageIDs"

"tags"

Example Request

[{
    "id": 20,
    "method": "messages.tag",
    "params": {
    	"action": "add",
    	"tags": ["javascript", "magma"],
        "messageIDs": [100, 101, 102],
    	"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.tag",
    "params": {
        "action": "replace",
    	"tags": [],
        "messageIDs": [100, 101, 102],
    	"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.tag",
    "params": {
        "action": "remove",
		"tags": ["almost", "done"],
	    "messageIDs": [100, 101, 102],
		"folderID": 1
    }
},{
    "id": 20,
    "method": "messages.tag",
    "params": {
        "action": "list",
	    "messageIDs": [100, 101, 102],
		"folderID": 1
    }
}]

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: messages.tags

back to contents

Get a list of all of the user's message tags from the server.

Response Params

Success just sends array of tags.

Example Response

[{
    "result": ["Important", "Work", "Personal", "To Do"]
}, {
    "error": true
}]

Method: meta

back to contents

Displays meta info in the main page. Browser, cookies, stylesheets, and connection security are detected by client.

Response Params

"userID"

"clientIP"

"location"

"reputation" - 0 to 100

"plan"

  1. "Free"
  2. "Basic"
  3. "Personal"
  4. "Enhanced"
  5. "Premium"

"version" - webmail version

"quota" - 0 to 100

Example Response

[{
    "result": {
        "userID": 32,
        "clientIP": "127.0.0.1",
        "location": "Dallas, TX",
        "timezone": "Central",
        "reputation": 88,
        "plan": "Basic",
        "version": "1.02",
        "quota": "45%",
        "javascript": true,
        "stylesheets": true,
        "connection": true
    }
}, {
    "error": true
}]

Method: scrape.add

back to contents

Add a scraped contact from the scraped contacts page. Any optional request params not present were empty submissions.

Request Params

"messageID"

"id" - temp id assigned by server from contacts.scrape method

"name"

"email"

["phone"]

["work"]

["cell"]

Example Request

{
    "id": 27,
    "method": "scrape.add",
    "params": {
        "messageID": 203,
        "id": 59,
        "name": "John Doe",
        "email": "jdoe@example.com"
    }
}

Example Response

[{
    "result": true
}, {
    "error": true
}]

Method: scrape

back to contents

Grab contacts from a message to display in the scraping screen.

Request Params

"messageID" - refers to message that contacts should be scraped from

Example Request

{
    "id": 28,
    "method": "scrape",
    "params": {
        "messageID": 203
    }
}

Response Params

"id" - temporary id assigned by server

"name"

"email"

["phone"]

["work"]

["cell"]

Example Response

[{
    "result": [{
        "contactID": 45,
        "name": "John Resig",
        "email": "jr@mozilla.org",
    }, {
        "contactID": 48,
        "name": "Linus Torvalds",
        "email": "lt@kernel.org",
    }, {
        "contactID": 53,
        "name": "Douglas Crockford",
        "email": "dc@yahoo.com",
    }, {
        "contactID": 58,
        "name": "Paul Graham",
        "email": "pg@ycombinator.com"
    }, {
        "contactID": 64,
        "name": "John Paul",
        "email": "jp@morgan.com"
    }]
}, {
    "error": true
}]
back to contents

Sent when searching with advanced search.

Request Params

"searchin"

"queries" - array of objects containing the following params

Example Request

{
    "id": 29,
    "method": "search",
    "params": {
        "searchin": 0,
        "queries": [{
            "field": "from",
            "filter": "contains",
            "query": "Paul Grahm"
        }, {
            "field": "date",
            "range": {
                "from": 23112342342,
                "to": 2342342343
            }
        }]
    }
}

Example Response

[{
    "result": [{
        "messageID": 1024,
        "flags": ["seen", "flagged"],
        "from": "William Adama",
        "to": "Apallo",
        "addressedTo": "apallo@lavabit.com",
        "replyTo": "bill@lavabit.com",
        "returnPath": "bill@lavabit.com",
        "subject": "Pegasus",
        "utc": 1109749011,
        "arrivalUtc": 1109749011,
        "snippet": "Go the the gym softy",
        "bytes": 487479772 
    }, {
        "messageID": 1023,
        "attachment": true,
        "from": "Douglas Crockford",
        "to": "John Resig",
        "addressedTo": "jresig@lavabit.com",
        "replyTo": "dcrock@lavabit.com",
        "returnPath": "dcrock@lavabit.com",
        "carbon": "mozilla@lavabit.com",
        "subject": "jQuery cruft",
        "utc": 1266415038183,
        "arrivalUtc": 1020030,
        "snippet": "jQuery is too crufty. YUI is much leaner.",
        "bytes": 895625721,
        "tags": ["Javascript"]
    }]
}, {
    "error": true
}]

Method: settings.identity

back to contents

Retrieve identity settings

Response Params

Returns settings that have been set.

"name" - the full name associated with the user account

"first" - the first name associated with the user account

"last" - the last name associated with the user account

"website"

Example Response

[{
    "result": {
        "name": "Lava Bit",
        "first": "Lava",
        "last": "Bit",
        "website": "lavabit.com"
    }
}, {
    "error": true
}]