MailHail API v1

Returns the authenticated mailbox, admin flags, delegated domains and token prefix when a bearer token is used.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/me

{
  "mailbox": "user@example.com",
  "global_admin": false,
  "domain_admins": ["example.com"],
  "token_prefix": "4f6c1e..."
}

Lists tokens owned by the authenticated mailbox, including grants, prefix and last-use metadata. Full secrets are never returned again.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/tokens

{
  "tokens": [
    {
      "id": 42,
      "name": "deploy",
      "prefix": "ab12cd34ef56",
      "grants": [{"permission":"mail.send","scope_type":"mailbox","scope_key":"user@example.com"}]
    }
  ]
}

Creates a scoped token. The returned token string is shown once. Grants cannot exceed the current user's effective permissions.

curl -X POST -H "Content-Type: application/json" -b mh-session.txt https://mailhail.com/api/v1/tokens -d @token.json

{
  "name": "deploy sender",
  "expires_at": "2026-06-14T00:00:00Z",
  "grants": [
    {"permission":"mail.send","scope_type":"mailbox","scope_key":"user@example.com"}
  ]
}

{
  "token": "mh_live_ab12cd34ef56_...",
  "record": {"id":42,"name":"deploy sender","prefix":"ab12cd34ef56"}
}

Revokes one of the current mailbox's API tokens.

curl -X DELETE -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/tokens/42

{"ok":true}

Returns folder metadata, total visible messages and unread counts for a mailbox.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" "https://mailhail.com/api/v1/mail/folders?mailbox=user@example.com"

{
  "mailbox": "user@example.com",
  "folders": [{"Name":"INBOX","Count":15731,"Unread":12}]
}

Returns a cursor-paginated message list. The list endpoint returns metadata and previews only, not full bodies.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" "https://mailhail.com/api/v1/mail/messages?mailbox=user@example.com&folder=INBOX&limit=50"

{
  "mailbox": "user@example.com",
  "messages": [{"row_id":24145,"subject":"Hello","seen":false}],
  "next_cursor": "MTcx..."
}

Returns sanitized body content, headers and attachment metadata for one message.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/mail/messages/24145

{
  "row_id": 24145,
  "subject": "Hello",
  "body_plain": "Message text",
  "attachments": [{"index":1,"filename":"invoice.pdf"}]
}

Streams the immutable raw message as message/rfc822.

curl -OJ -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/mail/messages/24145/raw

message/rfc822

Streams a decoded attachment by part index.

curl -OJ -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/mail/messages/24145/attachments/1

application/octet-stream or original content type

Supports set, add, remove and toggle. Thunderbird labels use $label1 through $label5.

curl -X PATCH -H "Authorization: Bearer $MAILHAIL_TOKEN" -H "Content-Type: application/json" https://mailhail.com/api/v1/mail/messages/24145/flags -d '{"op":"toggle","flags":["\\Flagged","$label1"]}'

{
  "op": "toggle",
  "flags": ["\\Flagged", "$label1"]
}

{
  "ok": true,
  "message": {"row_id":24145,"flagged":true,"label_priority":1}
}

Moves a message to another folder and assigns a new UID in the destination folder.

curl -X POST -H "Authorization: Bearer $MAILHAIL_TOKEN" -H "Content-Type: application/json" https://mailhail.com/api/v1/mail/messages/24145/move -d '{"folder":"Archive"}'

{"folder":"Archive"}

{"ok":true,"folder":"Archive"}

Moves non-Trash messages to Trash. Deleting from Trash enters the configured retention/tombstone path.

curl -X DELETE -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/mail/messages/24145

{"ok":true}

Sends mail as a mailbox. Local recipients are ingested directly, remote recipients are queued for outbound SMTP delivery.

curl -X POST -H "Authorization: Bearer $MAILHAIL_TOKEN" -H "Content-Type: application/json" https://mailhail.com/api/v1/mail/send -d @send.json

{
  "mailbox": "user@example.com",
  "to": ["friend@example.net"],
  "subject": "Hello",
  "text": "Message",
  "attachments": [{"filename":"note.txt","content_type":"text/plain","data_base64":"SGVsbG8="}]
}

{"ok":true}

Lists domains visible to the current principal. Bearer tokens still need a matching domain.settings.read grant.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/admin/domains

{"domains":[{"Name":"example.com","QuotaBytes":53687091200}]}

Returns retention, archive, tombstone, catch-all and limit settings for one domain.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" https://mailhail.com/api/v1/admin/domains/example.com

{"Name":"example.com","DefaultRetention":30,"QuotaBytes":53687091200}

Updates domain settings. Limit fields additionally require domain.quotas.write.

curl -X PATCH -H "Authorization: Bearer $MAILHAIL_TOKEN" -H "Content-Type: application/json" https://mailhail.com/api/v1/admin/domains/example.com -d '{"default_retention_days":30,"catch_all_email":"postmaster@example.com"}'

{
  "default_retention_days": 30,
  "catch_all_email": "postmaster@example.com",
  "quota_bytes": 53687091200
}

{"Name":"example.com","DefaultRetention":30,"CatchAllEmail":"postmaster@example.com"}

Returns mailbox metadata and usage summaries. It does not expose mailbox message contents to domain admins.

curl -H "Authorization: Bearer $MAILHAIL_TOKEN" "https://mailhail.com/api/v1/admin/mailboxes?domain=example.com"

{
  "domain": "example.com",
  "mailboxes": [{"Email":"user@example.com","MessageCount":15731,"StorageBytes":844000000}]
}