CloudMailin Send Email Message API

In order to send an email via API you can create a POST request to the Email Message endpoint:

POST: https://api.cloudmailin.com/api/v0.1/{SMTP_USERNAME}/messages.

Sending email via HTTP POST can be done via one of two methods:

If a client library is available for your Programming Language / Framework you can use a client library; Alternatively;
you can make an HTTP POST to our API manually to send the email

Client Libraries

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

Language / Framework	Status	Library	Link
node/typescript	released	`npm install --save cloudmailin`	link
go	beta	`go get -u github.com/cloudmailin/cloudmailin-go`	link
`ruby`	coming soon

We're adding new libraries regularly and this is an area under active development.

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

Sending Email with an API Call

If your Language / Framework isn't listed above then you can always make a request directly to the Outbound Email API.

You can also use any language / framework via SMTP.

Authentication

Authentication relies on your username and password from you SMTP credentials. You can find your SMTP credentials 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, alternatively you may wish to use SMTP, which is fully functional.

Email 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"
}