Direct REST sending
Your backend connects directly to Mail at https://mail.hubmail.space. Create a REST credential in the Mail project and scope it to the sender addresses your app may use. Dashboard bearer sessions do not authenticate to this API.
Base URL and authentication
Send Authorization: Bearer <REST key>. The key is shown only when created or rotated. Mail checks that the key is active, its domain is verified, and the sender belongs to its allowed aliases. For free addresses, Mail also enforces the owning account’s shared recipient allowance.
POST /v1/messages
The body is a complete RFC 5322/MIME message, not JSON. The visible From must be one address and must equal the envelope sender. Use a MIME library to generate valid headers, CRLF line endings, boundaries, and encoded non-ASCII text. Include both text and HTML parts when sending HTML.
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <REST key> |
Content-Type | Yes for this contract | message/rfc822 |
X-Envelope-From | Yes | One authorized sender address, matching the visible From header. |
X-Envelope-To | Yes | One or more comma-separated recipient addresses. |
Idempotency-Key | Recommended | A stable key for one logical message, at most 256 characters. |
X-Delivery-Mode | No | async by default; sync waits briefly for a local terminal/handoff state. |
X-Delivery-Timeout-Ms | No | When using sync, default wait is 5,000 ms and maximum is 25,000 ms. |
from email.message import EmailMessage
from email.policy import SMTP
from email.utils import formatdate, make_msgid
message = EmailMessage(policy=SMTP)
message["From"] = "notifications@example.com"
message["To"] = "person@example.net"
message["Subject"] = "Your receipt"
message["Date"] = formatdate(localtime=True)
message["Message-ID"] = make_msgid()
message.set_content("Thanks for your order.")
with open("message.eml", "wb") as output:
output.write(message.as_bytes())curl -X POST https://mail.hubmail.space/v1/messages \
-H "Authorization: Bearer $HUBFLY_MAIL_KEY" \
-H "Content-Type: message/rfc822" \
-H "X-Envelope-From: notifications@example.com" \
-H "X-Envelope-To: person@example.net" \
-H "Idempotency-Key: receipt-4821" \
--data-binary @message.emlAsynchronous success returns 202 Accepted and JSON such as {"id":"UUID","status":"queued"}. Synchronous mode still returns a local processing or handoff state; handed_to_postfix means Postfix accepted the message into its queue, not that the recipient received it.
GET /v1/messages/{id}
Use the same REST key to read a message submitted with that credential. The response includes ID, envelope sender, state, error, timestamps, byte size, and attempt count. A different key cannot read the message and receives a not-found result. Use the returned ID rather than an idempotency key in this path.
curl "https://mail.hubmail.space/v1/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $HUBFLY_MAIL_KEY"Two public REST operations
Retries and errors
| Status or code | Meaning | Action |
|---|---|---|
200 duplicate | Same credential, idempotency key, sender, recipients, and content were already submitted. | Keep the original returned ID; do not send again. |
400 invalid_message, invalid_from | Malformed MIME or visible From. | Generate a valid RFC 5322 message and retry with a new key if the content changes. |
400 invalid_sender, missing_recipients, invalid_recipient, invalid_idempotency_key | Envelope or retry key is invalid. | Correct sender and recipient addresses and keep the key within 256 characters. |
401 unauthorized | REST key is missing or invalid. | Use an active REST key, not a Dashboard token or SMTP password. |
403 sender_not_allowed, from_mismatch, credential_inactive, tenant_inactive | Sender, visible From, credential, or tenant is outside the allowed scope. | Check exact aliases, matching From, enabled state, and domain readiness. |
409 idempotency_conflict | The key was reused for different content. | Use a new key for the changed message. |
413 message_too_large | Raw message exceeds the configured limit. | Reduce MIME size, especially attachments. |
429 free_account_rate_limited | The shared free-domain recipient allowance was exceeded. | Wait for the window to reset or reduce recipients. |
429 credential_rate_limited, rate_limited | A credential or group sending cap was exceeded. | Wait for the relevant rate window; do not create another credential to bypass a policy. |
{
"error": {
"code": "sender_not_allowed",
"message": "sender is not permitted by credential"
}
}If the network times out after submission, retry the exact same bytes and envelope with the same idempotency key. Read message status if an ID was returned. An ambiguous local handoff state needs human review before a new send to avoid duplicates.
Limits and scope
The configured direct message-size default is 25 MiB, but the Mail node can set a different value. Free shared-domain sending is limited to 20 recipients/hour and 100 recipients/day across the owning account, including Dashboard and SMTP sends. Other credential and group caps can also apply.