Hubfly spaceDocs
Console

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.

HeaderRequiredValue
AuthorizationYesBearer <REST key>
Content-TypeYes for this contractmessage/rfc822
X-Envelope-FromYesOne authorized sender address, matching the visible From header.
X-Envelope-ToYesOne or more comma-separated recipient addresses.
Idempotency-KeyRecommendedA stable key for one logical message, at most 256 characters.
X-Delivery-ModeNoasync by default; sync waits briefly for a local terminal/handoff state.
X-Delivery-Timeout-MsNoWhen using sync, default wait is 5,000 ms and maximum is 25,000 ms.
Create message.eml with Python
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
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.eml

Asynchronous 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
curl "https://mail.hubmail.space/v1/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $HUBFLY_MAIL_KEY"

Two public REST operations

This API exposes message submission and credential-scoped status. It does not expose final recipient delivery attempts or message cancellation.

Retries and errors

Status or codeMeaningAction
200 duplicateSame credential, idempotency key, sender, recipients, and content were already submitted.Keep the original returned ID; do not send again.
400 invalid_message, invalid_fromMalformed 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_keyEnvelope or retry key is invalid.Correct sender and recipient addresses and keep the key within 256 characters.
401 unauthorizedREST 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_inactiveSender, visible From, credential, or tenant is outside the allowed scope.Check exact aliases, matching From, enabled state, and domain readiness.
409 idempotency_conflictThe key was reused for different content.Use a new key for the changed message.
413 message_too_largeRaw message exceeds the configured limit.Reduce MIME size, especially attachments.
429 free_account_rate_limitedThe shared free-domain recipient allowance was exceeded.Wait for the window to reset or reduce recipients.
429 credential_rate_limited, rate_limitedA credential or group sending cap was exceeded.Wait for the relevant rate window; do not create another credential to bypass a policy.
Direct Mail error shape
{
  "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.

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top