Email

Endpoint

To send email messages from your application you must perform a HTTP POST to the following endpoint:

http://127.0.0.1:43770/api/internal/messages

The above route exposes the complete messaging API of the bluecherry-client. Email is one of the communication channels that is free and no extra credits are required to make use of it. The BlueCherry platform allows a device to send two kinds of email messages:

1. Normal textual email which can have both HTML and plain text content.
2. An email with attachments, so called multipart email.

Normal email messages

Sending a normal email requires you to perform a POST request like in the following example:

POST /api/internal/messages HTTP/1.1
Host: 127.0.0.1:43770
Content-Type: application/json
Content-Length: 341

[
    {
        "type": 1,
        "destination": "john@johndoe.com",
        "subject": "This is a test subject",
        "plain": "Hi\r\n\r\nThis is a test plaintext email.\r\n\r\nKind regards,\r\nThe BlueCherry team",
        "html": "<p>Hi</p><p>This is a test plaintext email.</p><p>Kind regards,<br/>The BlueCherry team</p>"
    }
]

Every communication request body is a JSON array, this array contains one or more JSON message objects. The message body for a textual email contains the following required fields:

• type: '1' denotes that you want to send an email.
• destination: this field contains the email address of the recipient of the email.
• subject: this text field contains the email subject.
• plain: the application always sends multipart email messages to support both older and newer mail clients. This field contains the plaintext part of the email in which no HTML markup can be used.
• html: this field contains the HTML part of the email. Beware that many email clients only support a small subset of HTML and CSS. It is best to do some tests with the markup.

Email messages with attachments

Sending email messages with attachments can be handy to send status reports, images, ... To send an email message with attachments you must send the data as multipart/form-data and perform a request with the following example content and headers:

POST /api/internal/messages HTTP/1.1
Host: 127.0.0.1:43770
Content-Length: 770
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="destination"

john@johndoe.com
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="subject"

Test email with attachments
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="plain"

Hi\r\n\r\nThis is a test plaintext email.\r\n\r\nKind regards,\r\nThe BlueCherry team
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="html"

<p>Hi</p><p>This is a test plaintext email.</p><p>Kind regards,<br/>The BlueCherry team</p>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="funny_cat_image.jpg"
Content-Type: image/jpeg

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

The POST body is thus no longer JSON encoded but it consists out of multiple form fields:

• destination: this field contains the email address of the recipient of the email.
• subject: this text field contains the email subject.
• plain: the application always sends multipart email messages to support both older and newer mail clients. This field contains the plaintext part of the email in which no HTML markup can be used.
• html: this field contains the HTML part of the email. Beware that many email clients only support a small subset of HTML and CSS. It is best to do some tests with the markup.
• file: this fields contains the file metadata and also the binary contents of the attachment to send.