butterflyd ~error_handling

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:

{
	"command" : "authenticate",
	"request" : {
		"username" : "<username>",
		"password" : "<password>"
	}
}

JSON received:

{
	"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:

{
	"command" : "register",
	"request" : {
		"username" : "<username>",
		"password" : "<password>"
	}
}

JSON received:

{
	"status" : <statusCode>
}

Sending mail

To send mail the following TODO

JSON sent:

{
	"command" : "sendMail",
	"request" : {
		"mail" : {
			"recipients" : [],
			"message" : ...
		}
	}
}

JSON received:

{
	"status" : <statusCode>
}

Storing a mail message

You might want to simply save a mail message into a folder, perhaps for later editing.

JSON sent:

{
	"command" : "storeMail",
	"request" : {
		"mail" : {
			"recipients" : [],
			"message" : ...
		},
		"folder" : "<folderName>"
	}
}

JSON received:

{
	"status" : <statusCode>
}

Transporting mail

This is done by the server to forward mail to recipients not on the local server.

JSON sent:

{
	"command" : "deliverMail",
	"request" : {
		"mail" : {
			"recipients" : [],
			"message" : ...
		}
	}
}

JSON received:

{
	"status" : <statusCode>
}

Receiving mail

Receiving a message from the mail box, given the mail ID.

JSON sent:

{
	"command" : "fetchMail",
	"request" : {
		"id" : <mailID>
	}
}

JSON received:

{
	"status" : <statusCode>,
	"mail" : {
		"recipients" : [],
		"message" : ...
	}
}

Managing your mailbox

Adding a folder

JSON sent:

{
	"command" : "createFolder",
	"request" : {
		"folderName" : "<newFolderName>"
	}
}

TODO: received

Removing a folder

JSON sent:

{
	"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:

{
	"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:

{
	"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:

{
	"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.