Mailera API

Introduction

Every endpoint lives under one base URL and accepts and returns JSON.

1. 1Create an account and your own workspace (free).
2. 2Open Settings → API keys, create a key and choose its scopes.
3. 3Send the key in the X-API-Key header on every request.

Successful responses carry a data field; errors carry an error field with code and message.

Authentication

Send your API key in the X-API-Key header. Keys start with mh_live_ and are shown only once when created; if you lose one, create a new key and revoke the old one.

An Authorization header with a Bearer token holding the same key is also accepted.

Keys can be restricted to an IP allowlist; calls from other IPs get a 403.

Limits and pagination

Each key gets 300 requests per minute. Going over returns 429 with a Retry-After header.

Lists return next_cursor; send it back as the cursor parameter to get the next page. When there is no more data, next_cursor is null.

The limit parameter sets the page size.

Mailboxes

Add, check, sync, pause and delete mailboxes.

• GET/mailboxes

  List mailboxes

  Scope:

  read

  Query:

  status, q, cursor, limit

• POST/mailboxes/import

  Bulk import mailboxes (email:password:refresh_token:client_id, or | separated)

  Scope:

  import

  Body:

  lines, text, group_id, duplicate_mode

• GET/mailboxes/import

  Import progress and per-line results

  Scope:

  import

  Query:

  job_id

• GET/mailboxes/{id}

  Mailbox details and folder counters

  Scope:

  read

• PATCH/mailboxes/{id}

  Pause or resume a mailbox

  Scope:

  manage

  Body:

  action (required)

• DELETE/mailboxes/{id}

  Delete a mailbox

  Scope:

  manage

• GET/mailboxes/{id}/status

  Check live with Microsoft whether the mailbox still works

  Scope:

  read

• POST/mailboxes/{id}/sync

  Sync now

  Scope:

  sync

  Body:

  wait

Messages

Read, search, fetch OTP codes and send mail.

• GET/mailboxes/{id}/messages

  List messages in a folder

  Scope:

  read

  Query:

  folder, unread, cursor, limit

• GET/mailboxes/{id}/messages/{msgId}

  Get one message with its content

  Scope:

  read

• GET/mailboxes/{id}/otp

  Get the latest OTP code

  Scope:

  read

  Query:

  from, subject, since_minutes

• POST/mailboxes/{id}/send

  Send, reply or forward

  Scope:

  send

  Body:

  to, cc, bcc, subject, html, text, importance, reply_to_message_id, mode, attachments

• GET/messages/search

  Search mail across all mailboxes

  Scope:

  read

  Query:

  q, folder, limit

Spam

Check Inbox/Spam placement and move mail out of Spam.

• POST/mailboxes/{id}/messages/{msgId}/move

  Move a message (for example from Spam to Inbox)

  Scope:

  move

  Body:

  destination (required)

• POST/mailboxes/{id}/unspam

  Move all mail, or one sender's mail, out of Spam

  Scope:

  move

  Body:

  filter

• GET/mailboxes/{id}/placement

  Did the mail land in Inbox or Spam

  Scope:

  read

  Query:

  from, subject, since_minutes

Webhooks

Register URLs that receive events.

For every event, Mailera sends a JSON POST to your URL. If your endpoint errors or does not answer, Mailera retries with increasing delays.

To verify, compute HMAC-SHA256 of the timestamp, a dot and the body with the webhook secret, then compare it with the signature header.

Headers sent: X-MailHub-Event X-MailHub-Delivery X-MailHub-Timestamp X-MailHub-Signature

• GET/webhooks

  List webhooks

  Scope:

  webhooks

• POST/webhooks

  Create a webhook (the signing secret is returned once)

  Scope:

  webhooks

  Body:

  url (required), events, group_id

• PATCH/webhooks/{id}

  Enable/disable a webhook or change its events or URL

  Scope:

  webhooks

• DELETE/webhooks/{id}

  Delete a webhook

  Scope:

  webhooks