API

Overview

The DeveloperMail API allows simple programmatic access of mailbox functionality.

The following methods are supported by the API:

Create Mailbox
Delete Mailbox
Reset Mailbox Token
Get Message Ids
Get Messages
Send Message
Get Message
Delete Message

Name	Method	Url	Description	Authenticated
Create Mailbox	PUT	/api/mailbox	creates new mailbox	No
Delete Mailbox	DELETE	/api/mailbox/{name}	deletes mailbox	Yes
Reset Mailbox Token	PUT	/api/mailbox/{name}/token	generates a new mailbox token	Yes
Get Message Ids	GET	/api/mailbox/{name}	gets message ids of mailbox messages	Yes
Get Messages	POST	/api/mailbox/{name}/messages	gets messages for supplied message ids	Yes
Send Message	PUT	/api/mailbox/{name}/messages	sends email message from and to mailbox	Yes
Get Message	GET	/api/mailbox/{name}/messages/{id}	gets message from mailbox by id	Yes
Delete Message	DELETE	/api/mailbox/{name}/messages/{id}	deletes message from mailbox	Yes

Usage

This API is a RESTful API using JSON objects

Restrictions

The following restrictions for the API are in place:

More than 10 requests in 1 second(s) with result in a HTTP 429 Too Many Requests response

Responses

Responses from the API return a result array or object wrapped in an response object describing the result of the request and under normal operation will always return HTTP 200. In the event of a server or network error, the responses will be HTTP 5xx and should be handled appropriately.

The error object maps common HTTP error codes and messages for operations that are invalid such as HTTP 404 Not Found for mailboxes or messages that do not exist, and HTTP 403 Forbidden for authentication errors.

Sucessful Boolean Response Example

{
  "success": true,
  "errors": null,
  "result": true
}

Mailbox/Message Not Found Error Response Example

{
  "success": false,
  "errors": [
    {
      "code": 404,
      "message": "Not Found",
      "detail": "Not Found"
    }
  ],
  "result": false
}

Authentication Error Response Example

{
  "success": false,
  "errors": [
    {
      "code": 403,
      "message": "Not Authorized",
      "detail": "Not Authorized"
    }
  ],
  "result": false
}

Authentication

The API uses a simple authentication scheme requiring the X-MailboxToken custom HTTP header to be passed for all requests for a specific mailbox and/or message. This token is the only means for getting access to an existing mailbox and is treated as a bearer token such that any request for the mailbox or its messages using the token will be successful. This token should be kept secret and protected as such.

The create new mailbox method is the only method that does not require this header.

Methods

Create Mailbox

The create mailbox method creates a new mailbox with a random mailbox name.

HTTP Request Method

PUT

Request Url

https://www.developermail.com/api/v1/mailbox

Response

The response for the successful creation of a new mailbox contains the name of the mailbox and the token to be used for performing other operations on the mailbox and its messages.

Example Curl Command

curl -X PUT "https://www.developermail.com/api/v1/mailbox" -H "accept: application/json" -d ""

Example Response

{
  "success": true,
  "errors": null,
  "result": {
    "name": "z-zzzzz9",
    "token": "46401951EB619983ADA71A855FD02DD7DC5F63BD"
  }
}

Delete Mailbox

Deletes the mailbox specified

HTTP Request Method

DELETE

Request Url

https://www.developermail.com/api/v1/mailbox{name}

Response

Returns true if delete was successful, or false with error object describing the error.

Example Curl Command

curl -X DELETE "https://www.developermail.com/api/v1/mailbox/z-zzzzz9" -H "accept: application/json" -H "X-MailboxToken: 0C2F1C334A62905FB736391799D233A0EAAC60BF"

Example Response

{
  "success": true,
  "errors": null,
  "result": true
}

Reset Mailbox Token

The reset mailbox token method generates a new random token for the specified mailbox. All previous tokens are invalidated when a new token is generated.

Request Url

https://www.developermail.com/api/v1/mailbox/{name}/token

HTTP Request Method

PUT

Response

A successful response will return the mailbox name and new token in the same format as the create mailbox method.

Example Curl Command

curl -X PUT "https://www.developermail.com/api/v1/mailbox/z-zzzzz9/token" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD" -d ""

Example Response

{
  "success": true,
  "errors": null,
  "result": {
    "name": "z-zzzzz9",
    "token": "0C2F1C334A62905FB736391799D233A0EAAC60BF"
  }
}

Get Message Ids

The get message ids method returns an array of strings of message ids in the mailbox and are used for retrieving and deleting individual messages.

HTTP Request Method

GET

Request Url

https://www.developermail.com/api/v1/mailbox/{name}

Response

Returns an array of strings used for retrieveing and deleting messages. The strings can be converted to a 64-bit integer which is the number of ticks of the DateTime when the message was received. The 64-bit integer value can then be converted into a DateTime object. Depending on your programming language does not support converting ticks to DateTime you can subtract 621355968000000000 which is the number of ticks for 1970-01-01 and divide by 10000 which represents the total number of milliseconds since 1970-01-01.

Javascript Example:

        var messageKeyTicks = 636659727923143138;
        var ticks19700101 = 621355968000000000;
        var ticksDifference = messageKeyTicks - ticks19700101;
        var totalMillisecondsSince19700101 = ticksDifference / 10000;
        var messageReceived = new Date(totalMillisecondsSince19700101);
        console.log(messageReceived);

Example Curl Command

curl -X GET "https://www.developermail.com/api/v1/mailbox/z-zzzzz9" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD"

Example Response

{
  "success": true,
  "errors": null,
  "result": [
    "636659954289329835",
    "636659954395885084",
    "636659954415887041"
  ]
}

Get Messages

The get messages method returns an array of KeyValuePair<string,string> where the key is the messageId and the value is the raw mime message. The mime message can be converted to an MailKit.MimeMessage object using the nuget package located at https://www.nuget.org/packages/MimeKit/

HTTP Request Method

POST

Request Url

https://www.developermail.com/api/v1/mailbox/{name}/messages

Response

Array of KeyValuePair<string,string> containing message id as key and raw mime message as value.

Example Curl Command

curl -X POST "https://www.developermail.com/api/v1/mailbox/z-zzzzz9/messages" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD" -H "Content-Type: application/json" -d "[ \"636659954289329835\",\"636659954395885084\",\"636659954415887041\" ]"

Example Response

{
    "success": true,
    "errors": null,
    "result": [
        {
            "key": "636659954289329835",
            "value": "MIME-Version: 1.0\r\nFrom: z-zzzzz9@developermail.com\r\nTo: z-zzzzz9@developermail.com\r\nDate: 30 Jun 2018 22:43:48 +0000\r\nSubject: Test Subject\r\nContent-Type: text/plain; charset=us-ascii\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nTest Body\r\n"
        },
        {
            "key": "636659954395885084",
            "value": "MIME-Version: 1.0\r\nFrom: z-zzzzz9@developermail.com\r\nTo: z-zzzzz9@developermail.com\r\nDate: 30 Jun 2018 22:43:59 +0000\r\nSubject: Test Subject\r\nContent-Type: text/plain; charset=us-ascii\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nTest Body\r\n"
        },
        {
            "key": "636659954415887041",
            "value": "MIME-Version: 1.0\r\nFrom: z-zzzzz9@developermail.com\r\nTo: z-zzzzz9@developermail.com\r\nDate: 30 Jun 2018 22:44:01 +0000\r\nSubject: Test Subject\r\nContent-Type: text/plain; charset=us-ascii\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nTest Body\r\n"
        }
    ]
}

Send Message

Sends and email message both from and to the specified mailbox. The API does not support sending email to other mailboxes on developermail.com or any other email address.

HTTP Request Method

PUT

Request Url

https://www.developermail.com/api/v1/mailbox/{name}/messages

Response

Returns true if message is sent successfully

Example Curl Command

curl -X PUT "https://www.developermail.com/api/v1/mailbox/z-zzzzz9/messages" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD" -H "Content-Type: application/json" -d "{ \"subject\": \"string\", \"body\": \"string\", \"isHtml\": true}

Example Response

{
  "success": true,
  "errors": null,
  "result": true
}

Get Message

Get messages by Id returns the raw mime message for the mailbox and message.

HTTP Request Method

GET

Request Url

https://www.developermail.com/api/v1/mailbox/{name}/messages/{id}

Response

Raw mime message string (see Get Messages for additional information about mime message)

Example Curl Command

curl -X GET "https://www.developermail.com/api/v1/mailbox/z-zzzzz9/messages/636659954289329835" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD"

Example Response

{
  "success": true,
  "errors": null,
  "result": "MIME-Version: 1.0\r\nFrom: z-zzzzz9@developermail.com\r\nTo: z-zzzzz9@developermail.com\r\nDate: 30 Jun 2018 22:43:48 +0000\r\nSubject: Test Subject\r\nContent-Type: text/plain; charset=us-ascii\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nTest Body\r\n"
}

Delete Message

Deletes the message in the specified mailbox by id

HTTP Request Method

DELETE

Request Url

https://www.developermail.com/api/v1/mailbox/{name}/messages/{id}

Response

Returns true if delete was successful, or false with error object describing the error.

Example Curl Command

curl -X DELETE "https://www.developermail.com/api/v1/mailbox/z-zzzzz9/messages/636659954289329835" -H "accept: application/json" -H "X-MailboxToken: 46401951EB619983ADA71A855FD02DD7DC5F63BD"

Example Response

{
  "success": true,
  "errors": null,
  "result": true
}