CloudMailin Send Email Message API

To send an email via the API, create a POST request to the Email Message endpoint:

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

There are several ways to send email:

  • Use a client library if one is available for your language or framework
  • Make an HTTP POST with a JSON message — CloudMailin will construct the email for you
  • Make an HTTP POST with a raw RFC822 message — useful if you're building the email yourself or migrating from another provider

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 or framework isn't listed above you can make a request directly to the Outbound Email API.

You can also send email using any language or framework via SMTP.

Authentication

Authentication relies on your username and password from your 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 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.

JSON Message

The simplest way to send email is to POST a JSON object with the message fields. CloudMailin will construct the email for you.

Example

{
  "from": "Sender Name <sender@example.com>",
  "to": [
    "Recipient <recipient@example.com>",
    "Another <another@example.com>"
  ],
  "cc": [
    "Carbon Copy <cc@example.com>"
  ],
  "test_mode": false,
  "subject": "Hello from CloudMailin 😃",
  "tags": [
    "api-tag",
    "cloudmailin-tag"
  ],
  "plain": "Hello Plain Text",
  "html": "<h1>Hello Html</h1><p>An inline image: <img src=\"cid:pixel\" alt=\"just a CloudMailin blue pixel\" /></p>",
  "markdown": "# Hello Markdown\n\nThis is a **bold** message with a [link](https://example.com).\n",
  "headers": {
    "x-api-test": "Test",
    "x-additional-header": "Value"
  },
  "priority": "standard",
  "attachments": [
    {
      "file_name": "pixel.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAIAAAAC64paAAAAGklEQVR4nGPwrdpFNmIY1TyqeVTzqOaB1QwAF4tZrw174pgAAAAASUVORK5CYII=",
      "content_type": "image/png",
      "content_id": "pixel"
    }
  ]
}

Fields

Field Type Description
from string The from address of the email message. The from address will be replaced with an address used for bounce handling. For raw messages, this must match a From: header in the email.
to array of string or string One or more recipients for the email message. For raw messages, this must match a To: header in the email.
cc array of string or string One or more CC recipients for the email message. For raw messages, this must match a CC: header in the email.
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 array of string or string Tags that help filter the messages within the dashboard
plain string The plain text part of the email message. Either the plain text, html, or markdown parts are required.
html string The HTML part of the email message. Either the plain text, html, or markdown parts are required.
markdown string A markdown body for the email message. The markdown will be converted to HTML during delivery. If no plain part is provided, a plain text version will also be generated automatically. When combined with html, the HTML takes precedence and the markdown conversion is skipped. Can be combined with plain to provide your own plain text version. Note: This feature is not yet generally available. Contact support to enable it for your account.
priority string The delivery priority of the email message: standard (default), priority for higher priority delivery, or digest for batched delivery. Not all messages are eligible for priority delivery.
headers object See the headers section
attachments array of attachment objects See the attachments section

Attachments

Attachments 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:pixel" alt="Pixel" />

For example:

{
  "file_name": "pixel.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAIAAAAC64paAAAAGklEQVR4nGPwrdpFNmIY1TyqeVTzqOaB1QwAF4tZrw174pgAAAAASUVORK5CYII=",
  "content_type": "image/png",
  "content_id": "pixel"
}

Headers

Headers are not required as the subject, to and from headers will be set automatically. 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:

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

Raw Message

If you already have a constructed RFC822 email you can send it directly using the raw field instead of plain/html. This is useful if you're generating emails with your own library or migrating from another provider.

Example

{
  "from": "Sender Name <sender@example.com>",
  "to": [
    "Recipient <recipient@example.com>",
    "Another <another@example.com>"
  ],
  "cc": [
    "Carbon Copy <cc@example.com>"
  ],
  "test_mode": false,
  "subject": "Hello from CloudMailin 😃",
  "tags": [
    "api-tag",
    "cloudmailin-tag"
  ],
  "raw": "To: Recipient <recipient@example.com>, Another <another@example.com>\nFrom: Sender <sender@example.com>\nSubject: Test from Raw Email Message\nContent-Type: text/html;\n  charset=UTF-8\n\n<h1> Test Message: </h1>\n\n<p>Hi <strong>There</strong>,</p>\n<p>This is an example raw message.</p>\n<p>Thanks,<br />\nCloudMailin</p>\n"
}

Fields

Field Type Description
from string The from address of the email message. The from address will be replaced with an address used for bounce handling. For raw messages, this must match a From: header in the email.
to array of string or string One or more recipients for the email message. For raw messages, this must match a To: header in the email.
cc array of string or string One or more CC recipients for the email message. For raw messages, this must match a CC: header in the email.
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 array of string or string Tags that help filter the messages within the dashboard
raw string A full raw email. This should consist of both headers and a message body. To and From headers must be present and match those in the request. Multiple parts, text and html or other mixed content are acceptable but the message must be valid and RFC822 compliant. Any attachments intended to be sent in the Raw format must also be encoded and included here.