The following API specification is for Assignment #1 in PROG3170 - Programming: Distributed Apps Development due October 1, 2015.
- /api/v1/auth/
- /api/v1/mail/
- /api/v1/mail/{id}
- /api/v1/mailboxes/
- /api/v1/mailboxes/{email}
- /api/v1/mailboxes/{email}/access/
- /api/v1/mailboxes/{email}/access/{username}
Authenticate the user with the system and obtain the auth_key. All further API calls must have this key in header.
| Parameter | Required? |
|---|---|
| username | yes |
| password | yes |
| Code | Response |
|---|---|
| 200 | {"auth_key": <auth_key>} |
| 400 | {"error":"Please provide username."} |
| 403 | {"error":"API key is missing."} |
| Parameter | Required? | Description |
|---|---|---|
| api_key | yes | must be sent with all client requests. The api_key helps the server to validate the request source. |
List email ids that your token has access to.
| Parameter | Required? | Description |
|---|---|---|
| count | no | Limit the number of results to the specified integer. |
| cursor | no | Display count number of records starting at the cursor. |
| Code | Response |
|---|---|
| 200 | {"emails": [array of emails], "count": 300, "previous_page_id": "2c02b7b", "next_page_id": "1b91a6a" } |
| 400 | {"message": "invalid count"} |
| 401 | {"message": "unauthorized"} |
GET /api/v1/mail/?count=4{
"emails":[
{
"id":"e2ac585",
"read": true,
"status":"draft",
"to":"",
"cc":"joe@suremail.info",
"from":"bob@suremail.info",
"subject":"RE: Hi Bob",
"body":"This is a draft. Not sure what to put for a
subject or who to address this to, so I left them blank.
I do know that I want to cc joe though.\n--Bob"
},
{
"id":"d80369e",
"status":"inbox",
"read": false,
"to":"bob@suremail.info",
"from":"prince@i-am-a-prince.net",
"subject":"Not a scam!",
"body":"Dear Sir:\n\nI have been requested by the Nigerian
National Petroleum Company to contact you for assistance
in resolving a matter. The Nigerian National Petroleum
Company has recently concluded a large number of
contracts for oil exploration in the sub-Sahara region.
The contracts have immediately produced moneys equaling
US$40,000,000. The Nigerian National Petroleum Company is
desirous of oil exploration in other parts of the world,
however, because of certain regulations of the Nigerian
Government, it is unable to move these funds to another
region.\nYours truly,\nPrince Alyusi Islassis"
},
{
"id":"e2ac585",
"read": true,
"status":"sent",
"to":"joe@suremail.info",
"from":"bob@suremail.info",
"subject":"RE: Hi Bob",
"body":"Doing Great! Yourself?\n--Bob"
},
{
"id":"8890a59",
"read": true,
"status":"inbox",
"to":"bob@suremail.info",
"from":"joe@suremail.info",
"subject":"Hi Bob",
"body":"Hello Bob!\nHow are you?\n--Joe"
}
],
"count":12,
"next_email_id":"1b91a6a"
}Create an email
| Parameter | Required? | Description |
|---|---|---|
| auth_token | yes | - |
| status | yes | May be set to "draft" or "outbox" |
| to | yes* | - |
| cc | no | - |
| bcc | no | - |
| reply-to | no | Used when you want users to reply to something other than your "from" address |
| from | no | Defaults to the user's main email when omitted |
| subject | no | - |
| body | no | - |
| attachment | no | Multi-part encoded attachment(s) |
*fields are only validated when status is being set to "outbox".
Email objects being sent start at "draft" or "outbox". The mail server handles the outbox as a FIFO (first in first out) queue and does not block the client until the email has been sent.
| Code | Response |
|---|---|
| 201 | {"message": "draft saved"} |
| 202 | {"message": "email enqueued to be sent", "id", "1ba6a91"} |
| 400 | {"message": "missing to / status - stored email as draft", "id", "1ba6a91"} |
| 400 | {"message": "invalid to/from/cc/bcc/reply-to - stored email as draft", "id", "1ba6a91"} |
| 401 | {"message": "unauthorized from/reply-to - stored email as draft", "id", "1ba6a91"} |
| 500 | {"message": "mail not sent / draft not saved"} |
returns email object
update draft or send draft (change status to "outbox")
| Code | Response |
|---|---|
| 200 | {"message": "updated email"} |
| 202 | {"message": "email enqueued to be sent"} |
| 400 | {"message": "missing to / status - stored email as draft", "id", "1ba6a91"} |
| 400 | {"message": "invalid to/from/cc/bcc/reply-to - stored email as draft", "id", "1ba6a91"} |
| 401 | {"message": "unauthorized from/reply-to - stored email as draft", "id", "1ba6a91"} |
| 404 | {"message": "email not found"} |
| 500 | {"message": "mail not sent / draft not saved"} |
Delete an email
| Code | Response Body | Response Header |
|---|---|---|
| 202 | {"message": "mail deleted"} |
Location: /path/to/collection/ |
| 401 | {"message": "you may not delete this email"} |
- |
| 404 | {"message": "email not found"} |
- |
| 500 | {"message": "we could not delete this email, please try again later"} |
- |
returns the mailbox(es) your token has access to HEADERS: token [accept] PARAMS: [accept]
Deletes an email address
View a user's access to the mailbox
Grant mailbox access to a user
| Parameter | Description |
|---|---|
| allow_read | Set to true to allow a user to read emails from this mailbox |
| allow_send | Set to true to allow a user to send emails from this mailbox |
| allow_reply_to | Set to true to allow a user to use this address as their reply-to address |
| allow_delete | Set to true to allow a user to delete emails from this mailbox |
| allow_modify | Set to true to allow a user to modify, grant and revoke access |
Remove user from this mailbox's access list