CloudMailin Send Email Message API

In order to send an email via API you can create a POST request to the Message endpoint: POST: https://api.cloudmailin.com/api/v0.1/[SMTP_USERNAME]/messages

Authentication

Authentication relies on your username and password from you SMTP credentails. You can find your SMTP credentails for both live and test accounts on the SMTP Accounts page. Your SMTP username is part of the path used to make the SMTP request: POST: https://api.cloudmailin.com/api/v0.1/[SMTP_USERNAME]/messages

You then need to send your SMTP API Token. Authentication is via the Bearer token in the Authorization header as follows: Authorization: Bearer API_TOKEN.

This documentation is currently a work in progress. If you need help sending via the API please feel free to contact us, alterrnatively you may wish to use SMTP, which if fully functional.

Messages Endpoint Example

A full example POST can be seen below:

{
  "from": "Sender Name <sender@example.com>",
  "to": [
    "Recipient <recipient@example.com>",
    "Another <another@example.com>"
  ],
  "test_mode": false,
  "subject": "Hello from CloudMailin 😃",
  "tags": [
    "api-tag",
    "cloudmailin-tag"
  ],
  "plain": "Hello Plain Text",
  "html": "<h1>Hello Html</h1>",
  "headers": {
    "x-api-test": "Test",
    "x-additional-header": "Value"
  },
  "attachments": [
    {
      "file_name": "pixel.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP0rdr1HwAFHwKCk87e6gAAAABJRU5ErkJggg==",
      "content_type": "image/png",
      "content_id": null
    }
  ]
}

Below you can see an explanation of the fields, how to add attachments and how to set custom headers.

Fields

The API allows sending with the following fields:

Field Type Description
from string The from addrress of the email message. This is the address to be used in the SMTP transaction itself. Although it will be replaced with an address used for bounce handling. This must match a from: header in the email headers.
to The To addrress of the email message. This is the address to be used in the SMTP transaction itself. This must match a To: header in the email headers.
test_mode boolean Whether to send this message in test mode. This will validate the messge but no actually send it if true. If the server is in test mode then it will always be in test mode regardless of this value.
subject string The subject of the email. This will override any subject set in headers or raw messages.
tags Tags that help filter the messages within the dashboard
plain string The plain text part of the email message. Either the plain text or the html parts are required.
html string The HTML part of the email message. Either the plain text or the html parts are required.
headers object See the headers section
attachments Arrary of attachment objects See the attachments section

Attachments

Attachments are slightly more complicated and require the following fields

Field Type Description
file_name string The file name of the attachment
content string The Base64 encoded representation of the content. This shouldn't contain newlines within JSON.
content_type string The mime content type of the file such as image/jpeg
content_id string An optional content identifier. This is used to mark the attachment as inline and would allow inline display of the attachment within the html content. Within the HTML render an image tag for example with cid: <img src="cid:logo" alt="Logo" /> foo

For example this attaches a one-pixel image (Base64 encoded):

"attachments": [
  {
    "file_name": "pixel.png",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP0rdr1HwAFHwKCk87e6gAAAABJRU5ErkJggg==",
    "content_type": "image/png",
    "content_id": null
  }
]

Headers

Headers are not required as the subject, to and from headers will be set. However, if you need to specify additional headers you can pass them as an object. The key is the header name and the value is expected to be a string a string value:

"headers": {
  "x-api-test": "Test",
  "x-additional-header": "Value"
}

Libaries

Some languages and frameworks have official or community libraries to help get started:

Language / Framework Status Library
node/typescript beta npm install --save cloudmailin
ruby coming soon
go coming soon

In the meantime you can still use any language / framework via SMTP.

If you've created a community library we'd love to hear from you. Contact Us and let us know!