Sending

Send a message#

POST/v1/inboxes/{id}/messages

Sends a new message from the inbox and starts a new thread. The response is 201 with the message object, its direction set to out.

Addresses are lowercased and deduplicated; an address in to is dropped from cc and bcc. Bcc recipients get the message but never appear in its headers. The whole message, attachments included, may be at most 25 MB after encoding.

curl https://api.mailbay.dev/v1/inboxes/ibx_01jbz8w4k2q9/messages \
  -H "Authorization: Bearer $MAILBAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "bob@example.com",
    "subject": "Your report",
    "text": "Hi Bob, the report is attached.",
    "attachments": [
      { "filename": "report.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjcK..." }
    ]
  }'

The free sandbox#

Until your workspace has a verified domain, inboxes on your mailbay.email domain send in a sandbox, as Resend does: they can email the people in your workspace (the addresses they sign in with), other addresses under your own code, and the test addresses below. Any other recipient fails with 403 sandbox_recipient_not_allowed, and nothing is sent. The same rule applies to replies and to SMTP from a mail app. Verify a domain with mailbay domain add yourdomain.com and you can email anyone. GET /v1/me returns sandbox: true while the rule applies.

Test addresses#

Send to these from any inbox or project to see each outcome without real delivery. Mailbay simulates the result, updates the status and emits the event, and never adds them to your suppressions. A +tag works too, such as delivered+signup@test.mailbay.dev.

Idempotency#

Send an Idempotency-Key header (1 to 255 printable ASCII characters, a UUID works) on send and reply, and retrying after a timeout never sends twice. Keys are remembered per org for 24 hours.

Reply in a thread#

POST/v1/messages/{id}/reply

Replies to a message in the same thread. Mailbay sets In-Reply-To, References and a Re: subject, so the reply threads in Gmail and Outlook. A reply to received mail goes to its Reply-To if it had one, otherwise to its sender. A reply to one of your own sent messages follows up with its recipients.

curl https://api.mailbay.dev/v1/messages/msg_01jbz9c3/reply \
  -H "Authorization: Bearer $MAILBAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Thanks, on it", "reply_all": true}'

Message statuses#

A sent message moves forward through these statuses. Each change also emits an event, delivered to your webhooks.

With several recipients the message status summarizes them: complained wins, then deferred or sent while any recipient is still in flight, then bounced, failed and finally delivered.

Suppressions#

GET/v1/suppressions

DELETE/v1/suppressions/{address}

A hard bounce (the address does not exist) or a spam complaint adds the address to your org's suppression list, and sending to it fails with recipient_suppressed. Soft bounces and policy blocks do not suppress. The list returns address, reason (hard_bounce, complaint or manual) and created_at, newest first. Delete an entry only when you know the address works again. Both endpoints need an org scoped key.

curl -X DELETE https://api.mailbay.dev/v1/suppressions/bob@example.com \
  -H "Authorization: Bearer $MAILBAY_API_KEY"
# 204 No Content

Plan limits#

Every plan includes a number of sent recipients per calendar month (UTC); one message to three people counts as three. Received mail never counts. When the monthly limit is reached, sends fail with monthly_send_limit_reached until the first of next month. New orgs also send to at most 100 recipients a day for their first 7 days. See Pricing for each plan's numbers, and GET /v1/me for what you have used.

Automatic pause#

Mailbay sends from shared IPs, so it pauses a workspace whose mail hurts their reputation. Over the last 24 hours, once the workspace has sent to at least 50 recipients, sending pauses when hard bounces reach 5% of those recipients and number at least 3, or spam complaints reach 0.1% and number at least 3. A single complaint never pauses sending. Every recipient of every message counts, from the API, replies and SMTP alike; test addresses never count. The check runs each time a hard bounce or a complaint comes in.

While paused, every send and reply fails with sending_paused (403, SMTP 554 5.7.1), forwarding skips new mail, and the error message gives the reason, such as the hard bounce rate reached 6% (3 hard bounces among 50 recipients) in the last 24 hours. Receiving mail keeps working. The workspace owner gets one email, the dashboard shows a banner, the audit log records workspace.sending_paused, and webhooks get a sending.paused event. GET /v1/me returns the reason in org.paused_reason.

Only Mailbay support can resume sending; workspace owners cannot. Remove the addresses that bounced or complained (they are already suppressed), check where the rest of the list came from, then write to support@mailbay.dev with what changed. After a resume the rates are measured again from that moment.

Errors#