Email API
POST
/api/mail/send
Sending individual emails via Emercury SMTP service is straightforward. Simply make an HTTP POST request to our /api/mail/send endpoint, including the JSON message in the body.
Example request with curl
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Emercury-Token: api token" \
-d '{
"from": {"email": "[email protected]", "name": "Sender Name"},
"to": {"email": "[email protected]", "name": "Receiver Name"},
"subject": "Emercury SMTP Test",
"contents": [
{"contentType": "text/plain", "content": "Some plain message"},
{"contentType": "text/html", "content": "<html><body><strong>Hello user.</strong></body></html>"}
],
"replyTo": {"email": "[email protected]", "name": "Sender Name"}
}'
Authentication Headers
To authenticate with the service, use the X-Emercury-Token header for both authentication and authorization. In Emercury you can create a set of unique API tokens, which allows to manage access and data for each application connecting to the service.
The header name and value are not case sensitive. If the request contains incorrect or missing headers, an HTTP Response 401 (Unauthorized) will be returned.
Example header
X-Emercury-Token: api token
JSON Message Format
JSON messages should be included in the body of the HTTP POST request. The from and to fields can accept names in the format {"email": "[email protected]", "name": "John Doe"}. You can specify text/html for HTML-formatted messages, text/plain for plain text, or both for multipart messages. Multipart messages send HTML along with a text version for clients that do not support HTML.
The sender email must have a registered and confirmed sender signature. If not, you will receive an HTTP Response 422 (Unprocessable Entity).
For email addresses with names or titles containing punctuation, enclose them in quotes as follows: "name" : "\"Joe Receiver, Jr.\""
The subject line can be up to 500 characters, and the "From" address can be up to 255 characters. The length is calculated based on the number of UTF-16 code points, with code points in the range 0000 - FFFF counted as 1, and those above FFFF counted as 2.
Example JSON message format
{
"from": {"email": "[email protected]", "name": "Sender Name"},
"to": {"email": "[email protected]", "name": "Receiver Name"},
"subject": "Emercury SMTP Test",
"contents": [
{"contentType": "text/plain", "content": "Some plain message"},
{"contentType": "text/html", "content": "<html><body><strong>Hello user.</strong></body></html>"}
],
"replyTo": {"email": "[email protected]", "name": "Sender Name"}
}
Attachments
The SMTP HTTP API allows users to send email attachments by providing the contentType and content fields for each attachment.
contentType: Specifies the MIME type of the attachment (e.g., application/pdf for PDF files, image/jpeg for JPEG images). This helps the email client interpret the attachment correctly.
content: The actual content of the attachment, encoded in base64 format. Base64 encoding ensures that the attachment is transmitted correctly over the internet and can be decoded by the recipient’s email client
Note: Make sure the base64-encoded content is correctly generated to prevent data corruption during transmission
Allowed formats:
application/pdf, application/acrobat, application/nappdf, application/csv, application/x-pdf, image/pdf, image/png, image/apng, image/jpeg, image/pjpeg, image/vnd.mozilla.apng, image/jpeg2000-image, image/jp2, image/jpeg2000, image/x-jpeg2000-image, text/csv, text/x-comma-separated-values, text/x-csv
Example JSON message format
{
"from": {"email": "[email protected]", "name": "Sender Name"},
"to": {"email": "[email protected]", "name": "Receiver Name"},
"subject": "Emercury SMTP Test",
"contents": [
{"contentType": "text/html", "content": "<html><body><strong>Hello user.</strong></body></html>"},
{"contentType": "application/pdf", "content": "base64ofsomepdfdata", "name":"file.pdf"}
],
"replyTo": {"email": "[email protected]", "name": "Sender Name"}
}
Send a single email
POST
/api/mail/send
Request headers
Content-Type | required application/json |
Accept | required application/json |
X-Emercury-Token | required This request requires server level privileges. This token can be found on the Tokens page. |
Example request with curl
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Emercury-Token: api token" \
-d '{
"from": {"email": "[email protected]", "name": "Sender Name"},
"to": {"email": "[email protected]", "name": "Receiver Name"},
"subject": "Emercury SMTP Test",
"contents": [
{"contentType": "text/plain", "content": "Some plain message"},
{"contentType": "text/html", "content": "<html><body><strong>Hello user.</strong></body></html>"}
],
"replyTo": {"email": "[email protected]", "name": "Sender Name"}
}'
Body format
from | string | required The email address of the sender. It requires a registered and verified Sender Signature. To include a name along with the email, format it as "Full Name [email protected]". Any punctuation in the name should be properly escaped. |
to | string | required Recipient email address. |
subject | string | required Email subject |
contents | string | required You must specify text/plain or text/html |
replyTo | string | Reply-To Email address and name |
Example body format
{
"from": {"email": "[email protected]", "name": "Sender Name"},
"to": {"email": "[email protected]", "name": "Receiver Name"},
"subject": "Emercury SMTP Test",
"contents": [
{"contentType": "text/plain", "content": "Some plain message"},
{"contentType": "text/html", "content": "<html><body><strong>Hello user.</strong></body></html>"}
],
"replyTo": {"email": "[email protected]", "name": "Sender Name"}
}
Response
from | string | Sender's email address |
to | string | Recipient's email address |
subject | string | Subject of the message |
timestamp | string | Timestamp |
messageId | string | ID of the message |
code | string | Success or Error code |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": {
"code": "ok",
"details": null,
"request": {
"id": "2106202408444339146766753d7b5f931",
"timestamp": "1718959483.442780"
}
},
"data": {
"messageId": "b523648d-0a42-4209-a741-b28aba8dfc3d",
"from": "Sender Name <[email protected]>",
"to": "[email protected]",
"subject": "Emercury SMTP Test",
"timestamp": "2024-06-21T08:44:43+00:00"
}
}
Outbound Listing
GET
/api/mail/stats/outbound_listing
Outbound Listing API function returns all the emails sent within the specified time period. The response contains the status of sending for each email.
Request headers
Content-Type | required application/json |
Accept | required application/json |
X-Emercury-Token | required This request requires server level privileges. This token can be found on the Tokens page. |
Example request with curl
-X GET \
-H "Accept: application/json" \
-H "X-Emercury-Token: api token"
Query string parameters
dateFrom | required Filter messages starting from the date in format: YYYY-MM-DD |
dateTo | required Filter messages up to the date in format: YYYY-MM-DD |
toEmail | Filter by email address |
page | The number of the page to be returned |
perPage | Number of records to return per page |
Response
pagination | array | Returns the number of the page in response; number of records for this page; flag that indicates if there is a next page after the current one |
items | array | List of objects, each representing a single message |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": {
"code": "ok",
"details": null,
"request": {
"id": "21062024093247554277667548bf8752c",
"timestamp": "1718962367.644326"
}
},
"data": {
"items": [
{
"messageUuid": "b523648d-0a42-4209-a741-b28aba8dfc3d",
"fromEmail": "John Doe <[email protected]>",
"toEmail": "[email protected]",
"subject": "Some test email",
"status": "In Queue",
"sentDate": "2024-06-21T08:44:43+00:00"
},
{
"messageUuid": "346fe85c-2792-4f13-8e28-a6e8d7448cb7",
"fromEmail": "John Doe <[email protected]>",
"toEmail": "Name <[email protected]>",
"subject": "Hello World",
"status": "Hard Bounce",
"sentDate": "2024-06-14T15:33:33+00:00"
}
],
"pagination": {
"page": 1,
"itemsOnCurrentPage": 2,
"isMoreItems": false
}
}
}
Outbound Overview
GET
/api/mail/stats/outbound_overview
Outbound Overview API function returns statistics of statuses for the emails sent in a given time period.
Request headers
Content-Type | required application/json |
Accept | required application/json |
X-Emercury-Token | required This request requires server level privileges. This token can be found on the Tokens page. |
Example request with curl
curl "https://api.smtp.emercury.net/api/mail/stats/outbound_overview?dateFrom=2024-05-01&dateTo=2024-06-10" \
-X GET \
-H "Accept: application/json" \
-H "X-Emercury-Token: api token"
Querystring parameters
dateFrom | required Filter messages starting from the date in format: YYYY-MM-DD |
dateTo | required Filter messages up to the date in format: YYYY-MM-DD |
Response
sent | integer | Number of messages sent |
bounces | integer | Number of bounced messages |
apiErrors | integer | Number of api errors |
bounceRate | integer | Bounced emails rate |
spamComplaints | integer | Number of complaints |
spamComplaintsRate | integer | Complaints rate |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": {
"code": "ok",
"details": null,
"request": {
"id": "2106202409494007386566754cb412092",
"timestamp": "1718963380.198316"
}
},
"data": {
"sent": 22,
"bounced": 5,
"apiErrors": 2,
"bounceRate": 0.2,
"spamComplaints": 0.1,
"spamComplaintsRate": 0.1
}
}
Bounce types
Type | Name & Description |
HardBounce | Hard bounce — The server was unable to deliver your message. |
SoftBounce | Soft bounce — Unable to temporarily deliver message. |
2025©Emercury