CloudMailin API (0.1.0)

The CloudMailin Core API.

This is currently for private Beta, if an API key is required please contact us.

Account ID

Please note that all endpoint require sending the accountID as part of the URL. This can be found on your account page in the GUI.

However, for sending email over API this ID is the Username in your SMTP credentials.

Rate Limiting

Calls to the API are limited to 5 calls per minute.

Incoming Statuses

For some end points this may not be enough, specifically the incoming_statuses endpoint returns a fixed number of results and may receive faster than the results can be fetched. Please contact us if this is an issue.

Inbound Addresses

Inbound Addresses are referred to as Addresses in the API.

Each address receives email and forwards it to your HTTP endpoint as a POST request. To view messages received by an address, see Inbound Messages.

Get all addresses in the account

Authorizations:

bearerAPIToken

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "aaaa740b4c5c37b1aaaa",
"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}
]

Create an Address

Authorizations:

bearerAPIToken

Request Body schema: application/json

target required	string <uri> The target for the HTTP POST to be sent to.
target_format required	string Enum: "json+n" "multipart+n" The format of the HTTP POST request sent to the target.
nickname	string or null An optional, short, nickname for the address to help differeniate them.
	object or Attachment (object)

Responses

Request samples

Payload

Content type

application/json

{"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Response samples

201
401
403
422

Content type

application/json

{"id": "aaaa740b4c5c37b1aaaa",
"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Get a specific address

Authorizations:

bearerAPIToken

path Parameters

addressID

required

string (addressID)

Example: aaaa740b4c5c37b1aaaa

Identifier, please be aware that the format may change

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "aaaa740b4c5c37b1aaaa",
"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Update an Address

Updates an address with the specified ID.

Authorizations:

bearerAPIToken

path Parameters

addressID

required

string (addressID)

Example: aaaa740b4c5c37b1aaaa

Identifier, please be aware that the format may change

Request Body schema: application/json

target required	string <uri> The target for the HTTP POST to be sent to.
target_format required	string Enum: "json+n" "multipart+n" The format of the HTTP POST request sent to the target.
nickname	string or null An optional, short, nickname for the address to help differeniate them.
	object or Attachment (object)

Responses

Request samples

Payload

Content type

application/json

{"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Response samples

200
401
403
404
422

Content type

application/json

{"id": "aaaa740b4c5c37b1aaaa",
"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Delete an Address

Deletes an address with the specified ID. Note that a 202 response is expected. Deletion may not happen immediately.

Authorizations:

bearerAPIToken

path Parameters

addressID

required

string (addressID)

Example: aaaa740b4c5c37b1aaaa

Identifier, please be aware that the format may change

Responses

Response samples

202
401
403
404

Content type

application/json

{"id": "aaaa740b4c5c37b1aaaa",
"target": "http://www.cloudmailin.com/target/200",
"target_format": "json+n",
"nickname": null,
"attachments": { }
}

Inbound Messages

Inbound Messages are referred to as Incoming Statuses in the API.

Each message includes metadata such as sender, recipient, subject, and delivery status. Use the address_id parameter to filter messages for a specific address.

List inbound messages for a given address

Incoming statuses are ordered newest first. This doesn't really help with pagination as new records will be added frequently. A new scheme will be added in future to handle this issue more effectively.

Authorizations:

bearerAPIToken

query Parameters

address_id required	string (addressID) Example: address_id=aaaa740b4c5c37b1aaaa Identifier, please be aware that the format may change
page	integer Deprecated The page of results to return
query	string A query string to search the statuses for.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"message_id": "CAB=Hge+gC2LqXPu14qy82qPLk0YXcKrLeS7WZ3MPkOJJ-tMkMQ@mail.gmail.com",
"to": "recipient@example.net",
"from": "sender@example.net",
"status": 200,
"subject": "Example Subject Line",
"tls": "TLSv1.3",
"md5": "string",
"store_url": "https://example.s3.amazonaws.com/2021_12_01_00_00_00_34fab2ed3abb8dc60b8dc19194272a22.json",
"created_at": "2019-08-24T14:15:22Z"
}
]

Inbound Domains

Inbound Domains are referred to as Custom Domains in the API.

Custom domains allow you to receive email at your own domain (e.g., anything@yourdomain.com) instead of the default CloudMailin address.

Get all custom domains for a given address

Authorizations:

bearerAPIToken

query Parameters

address_id required	string (addressID) Example: address_id=aaaa740b4c5c37b1aaaa Identifier, please be aware that the format may change
page	integer Deprecated The page of results to return
query	string The domain to search for, partial domains are accepted.

Responses

Response samples

200
401
403
404

Content type

application/json

[{"id": "aaaa111122223333",
"domain": "example.com",
"auth_regex": "allowed[0-9]*@example.com",
"domain_target": "https://www.cloudmailin.com/target/201"
}
]

Create a custom domain for a given address

Authorizations:

bearerAPIToken

query Parameters

address_id

required

string (addressID)

Example: address_id=aaaa740b4c5c37b1aaaa

Identifier, please be aware that the format may change

Request Body schema: application/json

domain required	string The domain to receive email on. MX records for the domain must already be set.
auth_regex	string or null
domain_target	string or null Domain target changes the address target for this specific Custom Domain. This feature is not available to all accounts.

Responses

Request samples

Payload

Content type

application/json

{"domain": "example.com",
"auth_regex": "allowed[0-9]*@example.com",
"domain_target": "https://www.cloudmailin.com/target/201"
}

Response samples

201
401
403
404
422

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"auth_regex": "allowed[0-9]*@example.com",
"domain_target": "https://www.cloudmailin.com/target/201"
}

Delete a Custom Domaiin with the given id

Note that a 202 response is expected. Deletion may not happen immediately.

Authorizations:

bearerAPIToken

path Parameters

customDomainID

required

string (customDomainID) [0-9a-f]{16}

Example: aaaa111122223333

Identifier, please be aware that the format may change

query Parameters

address_id

required

string (addressID)

Example: address_id=aaaa740b4c5c37b1aaaa

Identifier, please be aware that the format may change

Responses

Response samples

202
401
403
404

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"auth_regex": "allowed[0-9]*@example.com",
"domain_target": "https://www.cloudmailin.com/target/201"
}

Messages

Send email messages via the API.

Messages can also be sent via SMTP. Use the Outbound Messages endpoints to retrieve sent messages and track their delivery status.

Message Events Webhook

The message events webhook will send events relating to the delivery of messages sent via SMTP or the API. This information includes bounce and delivery statuses. Each post will be an array of one or more events.

Authorizations:

bearerAPIToken

Request Body schema: application/json

Array of objects (MessageEvent)

Request samples

Payload

Content type

application/json

{"events": [{"kind": "delivery",
"message_id": "544a9141-8924-4d70-899c-4e1a4dd860d1",
"recipient": "from@example.com",
"original_message_id": "something-you-set@example.com",
"timestamp": "2023-06-27T22:30:00.000Z"
}
]
}

Create a new Email Message for a given outbound account (server)

Authorizations:

smtpAuth

Request Body schema: application/json

One of

from required	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.
required	Array of strings or string One or more recipients for the email message. For raw messages, this must match a `To:` header in the email.
	Array of strings 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.
	Array of strings 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.
	object
priority	string Enum: "standard" "priority" "digest" 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.
	Array of objects (MessageAttachment)

Responses

Request samples

Payload

Content type

application/json

Example

Message

{"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"
}
]
}

Response samples

202
401
422

Content type

application/json

{"id": "string",
"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"
]
}

Outbound Messages

Beta — These endpoints are functional but may change without notice. We'd love feedback on what works and what doesn't.

Retrieve sent email messages and their delivery events.

To send messages, use SMTP or the POST /messages endpoint. This section provides endpoints to retrieve those messages and track delivery status.

Each message has one or more recipients, and each recipient has a series of events tracking the delivery lifecycle (e.g., registration, dispatch, delivery, open, click).

Get all sent messages for an outbound account Beta

Returns a paginated list of sent messages for the specified outbound account. Messages are ordered newest first.

Messages are created by sending email via SMTP or the POST /messages endpoint. This endpoint retrieves those messages along with their delivery status.

Each message includes a recipients array showing the current last_event for each recipient. Use the show endpoint to get full event history.

Authorizations:

bearerAPIToken

query Parameters

outbound_account_id required	string (outboundAccountID) [0-9a-f]{16} Example: outbound_account_id=aaaa111122223333 The outbound account ID (shown as ID/Username in the dashboard)
page	integer Deprecated The page of results to return
query	string A query string to search the messages for.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "724b9ef2-94ee-4fb0-b722-082204633911",
"from": "sender@example.com",
"subject": "Hello from CloudMailin",
"message_id": "<724b9ef2-94ee-4fb0-b722-082204633911@cloudmta.net>",
"to": ["recipient@example.com"
],
"cc": [ ],
"tags": ["marketing",
"newsletter"
],
"test_mode": false,
"created_at": "2019-08-24T14:15:22Z",
"recipients": [{"email": "recipient@example.com",
"last_event": "delivery"
}
]
}
]

Get a specific sent message with event history Beta

Returns a sent message with full event history for each recipient.

The recipients array includes an events array showing all delivery events (e.g., registration, dispatch, delivery, open, click) in chronological order.

Note: Internal events (process, spamd, complaint) are excluded from the response.

Authorizations:

bearerAPIToken

path Parameters

outboundMessageID

required

string <uuid> (outboundMessageID)

Example: 724b9ef2-94ee-4fb0-b722-082204633911

The CloudMailin outbound message ID (UUID)

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "724b9ef2-94ee-4fb0-b722-082204633911",
"from": "sender@example.com",
"subject": "Hello from CloudMailin",
"message_id": "<724b9ef2-94ee-4fb0-b722-082204633911@cloudmta.net>",
"to": ["recipient@example.com"
],
"cc": [ ],
"tags": ["marketing",
"newsletter"
],
"test_mode": false,
"created_at": "2019-08-24T14:15:22Z",
"recipients": [{"email": "recipient@example.com",
"last_event": "delivery",
"events": [{"kind": "delivery",
"timestamp": "2019-08-24T14:15:22Z",
"details": {"agent": "DSN",
"reply_code": "250",
"delivery_status": "2.0.0",
"smtp_response": "250 2.0.0 OK",
"remote_host": "aspmx.l.google.com"
}
}
]
}
]
}

Outbound Domains

Outbound Domains are referred to as Sending Domains in the API.

Before sending email from a domain, you must add it and verify your DNS records.

Add the domain — POST /sending_domains with your domain name
Create DNS records — the response includes the SPF and DKIM records you need to add to your DNS
Verify — POST /sending_domains/{id}/verify to check the records are in place

Get all outbound domains in the account

Authorizations:

bearerAPIToken

query Parameters

page	integer Deprecated The page of results to return
query	string The domain to search for, partial domains are accepted.

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "aaaa111122223333",
"domain": "example.com",
"mta_domain": "mta.example.com",
"dkim_selector": "0e7c28e2e4cm",
"dkim_domain": "0e7c28e2e4cm._domainkey.example.com",
"dkim_public_record": "v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPzZ1k4BjmTZbaS43mhI+HJE2seKeudrExH7kd7YzQ7H0Ci3BBvzQkh6WjUGdibEUOgdo0Mm4VN4H6myc9LvX8qpM+C4MaBNW3hr2kOG/nKSI+Gp0usSj+THc3/4u1+J7IhKBuKaZdj4k5uDKcwKw3uM3RDiwQjppVJvORhuvoMfsGjD296FatQf53j9XExxM4j2ugLnHdhtXtVsGfQb3DoE87Hzc2W6wg7Je3C8eZZ/w9cI2OHBFL3xi39dgwOlbMrLUqTPtvIl+aRMikGS2RZadiGEPnXVS3Ac57ekqprDD7M7Uapyn2a0NX4A/VOtWOFceXSk6iHBbDlM/fO3SwIDAQAB",
"required_cname": "feedback-smtp.cloudmta.net",
"dkim_verified": true,
"return_path_verified": true,
"spf_verified": true
}
]

Create an Outbound Sending Domain for a given account

Authorizations:

bearerAPIToken

Request Body schema: application/json

domain

string

The domain used for sending mail

Responses

Request samples

Payload

Content type

application/json

{"domain": "example.com"
}

Response samples

201
401
422

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"mta_domain": "mta.example.com",
"dkim_selector": "0e7c28e2e4cm",
"dkim_domain": "0e7c28e2e4cm._domainkey.example.com",
"dkim_public_record": "v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPzZ1k4BjmTZbaS43mhI+HJE2seKeudrExH7kd7YzQ7H0Ci3BBvzQkh6WjUGdibEUOgdo0Mm4VN4H6myc9LvX8qpM+C4MaBNW3hr2kOG/nKSI+Gp0usSj+THc3/4u1+J7IhKBuKaZdj4k5uDKcwKw3uM3RDiwQjppVJvORhuvoMfsGjD296FatQf53j9XExxM4j2ugLnHdhtXtVsGfQb3DoE87Hzc2W6wg7Je3C8eZZ/w9cI2OHBFL3xi39dgwOlbMrLUqTPtvIl+aRMikGS2RZadiGEPnXVS3Ac57ekqprDD7M7Uapyn2a0NX4A/VOtWOFceXSk6iHBbDlM/fO3SwIDAQAB",
"required_cname": "feedback-smtp.cloudmta.net",
"dkim_verified": true,
"return_path_verified": true,
"spf_verified": true
}

Get a specific Outbound Sending Domain

Authorizations:

bearerAPIToken

path Parameters

sendingDomainID

required

string (sendingDomainID) [0-9a-f]{16}

Example: aaaa111122223333

Identifier, please be aware that the format may change

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"mta_domain": "mta.example.com",
"dkim_selector": "0e7c28e2e4cm",
"dkim_domain": "0e7c28e2e4cm._domainkey.example.com",
"dkim_public_record": "v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPzZ1k4BjmTZbaS43mhI+HJE2seKeudrExH7kd7YzQ7H0Ci3BBvzQkh6WjUGdibEUOgdo0Mm4VN4H6myc9LvX8qpM+C4MaBNW3hr2kOG/nKSI+Gp0usSj+THc3/4u1+J7IhKBuKaZdj4k5uDKcwKw3uM3RDiwQjppVJvORhuvoMfsGjD296FatQf53j9XExxM4j2ugLnHdhtXtVsGfQb3DoE87Hzc2W6wg7Je3C8eZZ/w9cI2OHBFL3xi39dgwOlbMrLUqTPtvIl+aRMikGS2RZadiGEPnXVS3Ac57ekqprDD7M7Uapyn2a0NX4A/VOtWOFceXSk6iHBbDlM/fO3SwIDAQAB",
"required_cname": "feedback-smtp.cloudmta.net",
"dkim_verified": true,
"return_path_verified": true,
"spf_verified": true
}

Delete the specified Outbound Sending Domain

Note that a 202 response is expected. Deletion may not happen immediately.

Authorizations:

bearerAPIToken

path Parameters

sendingDomainID

required

string (sendingDomainID) [0-9a-f]{16}

Example: aaaa111122223333

Identifier, please be aware that the format may change

Responses

Response samples

202
401
403
404

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"mta_domain": "mta.example.com",
"dkim_selector": "0e7c28e2e4cm",
"dkim_domain": "0e7c28e2e4cm._domainkey.example.com",
"dkim_public_record": "v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPzZ1k4BjmTZbaS43mhI+HJE2seKeudrExH7kd7YzQ7H0Ci3BBvzQkh6WjUGdibEUOgdo0Mm4VN4H6myc9LvX8qpM+C4MaBNW3hr2kOG/nKSI+Gp0usSj+THc3/4u1+J7IhKBuKaZdj4k5uDKcwKw3uM3RDiwQjppVJvORhuvoMfsGjD296FatQf53j9XExxM4j2ugLnHdhtXtVsGfQb3DoE87Hzc2W6wg7Je3C8eZZ/w9cI2OHBFL3xi39dgwOlbMrLUqTPtvIl+aRMikGS2RZadiGEPnXVS3Ac57ekqprDD7M7Uapyn2a0NX4A/VOtWOFceXSk6iHBbDlM/fO3SwIDAQAB",
"required_cname": "feedback-smtp.cloudmta.net",
"dkim_verified": true,
"return_path_verified": true,
"spf_verified": true
}

Verify (Check) the DNS records have been set for the given domain

Authorizations:

bearerAPIToken

path Parameters

sendingDomainID

required

string (sendingDomainID) [0-9a-f]{16}

Example: aaaa111122223333

Identifier, please be aware that the format may change

Responses

Response samples

200
401
403
404
422

Content type

application/json

{"id": "aaaa111122223333",
"domain": "example.com",
"mta_domain": "mta.example.com",
"dkim_selector": "0e7c28e2e4cm",
"dkim_domain": "0e7c28e2e4cm._domainkey.example.com",
"dkim_public_record": "v=DKIM1; h=sha256; k=rsa; s=email; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzPzZ1k4BjmTZbaS43mhI+HJE2seKeudrExH7kd7YzQ7H0Ci3BBvzQkh6WjUGdibEUOgdo0Mm4VN4H6myc9LvX8qpM+C4MaBNW3hr2kOG/nKSI+Gp0usSj+THc3/4u1+J7IhKBuKaZdj4k5uDKcwKw3uM3RDiwQjppVJvORhuvoMfsGjD296FatQf53j9XExxM4j2ugLnHdhtXtVsGfQb3DoE87Hzc2W6wg7Je3C8eZZ/w9cI2OHBFL3xi39dgwOlbMrLUqTPtvIl+aRMikGS2RZadiGEPnXVS3Ac57ekqprDD7M7Uapyn2a0NX4A/VOtWOFceXSk6iHBbDlM/fO3SwIDAQAB",
"required_cname": "feedback-smtp.cloudmta.net",
"dkim_verified": true,
"return_path_verified": true,
"spf_verified": true
}