260 lines
3.5 KiB
Markdown
260 lines
3.5 KiB
Markdown
butterflyd
|
|
==========
|
|
|
|
[![Build Status](https://travis-ci.org/thebutterflyprotocol/butterflyd.svg?branch=master)](https://travis-ci.org/thebutterflyprotocol/butterflyd)
|
|
|
|
**Butterfly** is an easy-to-use email protocol replacement. It aims at being easy to extend on the client end by using JSON as the basis for the majority of the protocol.
|
|
|
|
## Protocol
|
|
|
|
### Authentication
|
|
|
|
To connect to a Butterfly server one must first autheticate themselves with the server. The JSON provided and returned for this are shown below:
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "authenticate",
|
|
"request" : {
|
|
"username" : "<username>",
|
|
"password" : "<password>"
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <status>,
|
|
}
|
|
```
|
|
|
|
### Registration
|
|
|
|
To register a new account on the server one must provide the username (`<username>`) and password (`<password>`) wanting to be used as shown below:
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "register",
|
|
"request" : {
|
|
"username" : "<username>",
|
|
"password" : "<password>"
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <statusCode>
|
|
}
|
|
```
|
|
|
|
### Sending mail
|
|
|
|
To send mail the following TODO
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "sendMail",
|
|
"request" : {
|
|
"mail" : {
|
|
"recipients" : [],
|
|
"message" : ...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <statusCode>
|
|
}
|
|
```
|
|
|
|
### Storing a mail message
|
|
|
|
You might want to simply save a mail message into a folder, perhaps for later editing.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "storeMail",
|
|
"request" : {
|
|
"mail" : {
|
|
"recipients" : [],
|
|
"message" : ...
|
|
},
|
|
"folder" : "<folderName>"
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <statusCode>
|
|
}
|
|
```
|
|
|
|
### Transporting mail
|
|
|
|
This is done by the server to forward mail to recipients not on the local server.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "deliverMail",
|
|
"request" : {
|
|
"mail" : {
|
|
"recipients" : [],
|
|
"message" : ...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <statusCode>
|
|
}
|
|
```
|
|
|
|
### Receiving mail
|
|
|
|
Receiving a message from the mail box, given the mail ID.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "fetchMail",
|
|
"request" : {
|
|
"id" : <mailID>
|
|
}
|
|
}
|
|
```
|
|
|
|
JSON received:
|
|
|
|
```json
|
|
{
|
|
"status" : <statusCode>,
|
|
"mail" : {
|
|
"recipients" : [],
|
|
"message" : ...
|
|
}
|
|
}
|
|
```
|
|
|
|
### Managing your mailbox
|
|
|
|
#### Adding a folder
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "createFolder",
|
|
"request" : {
|
|
"folderName" : "<newFolderName>"
|
|
}
|
|
}
|
|
```
|
|
|
|
TODO: received
|
|
|
|
#### Removing a folder
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "deleteFolder",
|
|
"request" : {
|
|
"folderName" : "<folderName>"
|
|
}
|
|
}
|
|
```
|
|
|
|
TODO: received
|
|
|
|
#### Adding a mail message to a folder
|
|
|
|
Binds a message by `"mailID"` to the given folder `"<folderName>"`.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "addToFolder",
|
|
"request" : {
|
|
"folderName" : "<folderName>",
|
|
"mailID" : <mailID>
|
|
}
|
|
}
|
|
```
|
|
|
|
TODO: received
|
|
|
|
#### Removing a mail message from a folder
|
|
|
|
Unbinds a message by `"mailID"` to the given folder `"<folderName>"`.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "removeFromFolder",
|
|
"request" : {
|
|
"folderName" : "<folderName>",
|
|
"mailID" : <mailID>
|
|
}
|
|
}
|
|
```
|
|
|
|
TODO: received
|
|
|
|
#### Getting a list of all mailIDs in a folder
|
|
|
|
Retrieves a list of mail IDs on the given folder `"<folderName>"`.
|
|
|
|
JSON sent:
|
|
|
|
```json
|
|
{
|
|
"command" : "listMail",
|
|
"request" : {
|
|
"folderName" : "<folderName>"
|
|
}
|
|
}
|
|
```
|
|
|
|
TODO: received
|
|
|
|
#### Deleting mail
|
|
|
|
Mail messages just exist but are bound to folders. As soon as it has no references, it gets deleted.
|
|
|
|
JSON sent:
|
|
|
|
etc. **TODO**
|
|
|
|
|
|
|
|
Later
|
|
TODO: Since we going to do push too, we will therefore need to have eventIDs on send to do matching up. |