Inbox API

• check_circleMethod: Bearer API key (Authorization: Bearer <api_key>) or X-Api-Key.
• check_circlePermissions:
  • inbound for POST /api/v1/mail/inbound
  • read for email retrieval endpoints
  • write for read/delete/update actions
  • webhook for webhook registration endpoints
• check_circleinbound for POST /api/v1/mail/inbound
• check_circleread for email retrieval endpoints
• check_circlewrite for read/delete/update actions
• check_circlewebhook for webhook registration endpoints

Common errors:

{ "status": "error", "reason": "API key is required." }

{ "status": "error", "reason": "API key does not have webhook permission." }

For POST /api/v1/create/mailbox/bulk and the follow-up GET /api/v1/get/mailbox/bulk task polling:

• check_circleExisting mailbox addresses are skipped automatically and do not fail the task.
• check_circleTask completion still returns status=completed when every requested address already exists.
• check_circleIn that all-existing case, total_email is 0 and results is empty.

POST /api/v1/mail/inbound

Receives inbound email payload from upstream mail provider.

Required request fields:

• check_circlemessage_id string (unique per mailbox)
• check_circlefrom_email string email
• check_circleto_email string email
• check_circlesubject string
• check_circlereceived_at ISO timestamp

Optional:

• check_circlefrom_name, cc[], bcc[], body_text, body_html, headers, in_reply_to, references[]
• check_circleattachments[] (filename, mime_type, size, and either content base64 or content_url)

curl -X POST "$APP_URL/api/v1/mail/inbound" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg-12345",
    "from_email": "sender@example.com",
    "to_email": "support@mails.now",
    "subject": "Need help",
    "body_text": "Hello team",
    "received_at": "2026-04-27T12:10:00Z"
  }'

{
  "status": "accepted",
  "message_id": "msg-12345"
}

Error examples:

• check_circle401 invalid/missing API key
• check_circle403 missing inbound permission
• check_circle422 unknown mailbox or validation error

Mailcow IMAP bridge rollout

IMAP polling ingests mail in-process in the application that runs the poller (mailbridge:poll-inbound): messages are normalized and dispatched without an HTTP loopback or bridge-specific API keys.

1. Set MAILBRIDGE_POLL_ENABLED=true when you want Laravel’s scheduler to run mailbridge:poll-inbound every 30 minutes (see routes/console.php).
2. Set MAILBRIDGE_QUEUE=inbound and run a queue worker that listens to the inbound queue (recommended: a dedicated Supervisor program separate from default / mailcow workers).
3. Only mailboxes with Active status and Ready provisioning (provisioning_status = active) that have IMAP credentials or a stored password are scheduled for polling.
4. Run php artisan mailbridge:poll-inbound manually and inspect bridge logs/dead-letter rows until behavior is stable.
5. Roll out mailbox-by-mailbox (e.g. --mailbox=ID) before relying on scheduler-driven polling for all boxes.
6. Users can still trigger an immediate poll from the Inbox Refresh button; those jobs are queued on inbound for all pollable active mailboxes in their tenant.

Tenant integrations may still POST to /api/v1/mail/inbound with a normal workspace API key and inbound permission—that path is unrelated to IMAP polling.

Dead-letter replay:

php artisan mailbridge:replay-deadletters --id=123
php artisan mailbridge:replay-deadletters --mailbox=10
php artisan mailbridge:replay-deadletters --all

GET /api/v1/emails

Query params:

• check_circlemailbox_id
• check_circleunread=true|false
• check_circlesince=ISO_TIMESTAMP
• check_circlebefore=ISO_TIMESTAMP
• check_circleq=keyword
• check_circlecursor pagination via cursor

Example:

curl -H "Authorization: Bearer $API_KEY" \
  "$APP_URL/api/v1/emails?mailbox_id=10&unread=true&q=invoice"

Response:

{
  "data": [
    {
      "id": 101,
      "mailbox_id": 10,
      "thread_id": 44,
      "message_id": "msg-123",
      "from_email": "billing@example.com",
      "to_email": "ops@mails.now",
      "subject": "Invoice",
      "body_text": "Please review",
      "body_html": "<p>Please review</p>",
      "is_read": false,
      "is_deleted": false,
      "is_spam": false,
      "spam_score": 0,
      "received_at": "2026-04-27T10:00:00Z",
      "updated_at": "2026-04-27T10:00:01Z",
      "attachments": []
    }
  ],
  "meta": {
    "next_cursor": null,
    "prev_cursor": null
  }
}

GET /api/v1/emails/{id}

Returns one email scoped to tenant.

GET /api/v1/emails/sync?since=ISO_TIMESTAMP

Returns only records where updated_marker_at >= since for incremental polling clients.

POST /api/v1/emails/{id}/read

Marks email read and emits email.read webhook event.

curl -X POST -H "Authorization: Bearer $API_KEY" \
  "$APP_URL/api/v1/emails/101/read"

DELETE /api/v1/emails/{id}

Soft-deletes email and emits email.deleted.

GET /api/v1/emails/{id}/attachments/{attachment_id}

Returns a short-lived signed URL.

Response:

{
  "data": {
    "url": "https://app.test/api/v1/downloads/attachments/9?expires=...",
    "expires_at": "2026-04-27T12:15:00Z"
  }
}

POST /api/v1/webhooks

Registers tenant webhook endpoint.

Payload:

• check_circleurl (required URL)
• check_circleevents[] (email.received, email.read, email.deleted)
• check_circleis_active optional bool

Example:

curl -X POST "$APP_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://client.example/webhooks/email","events":["email.received","email.deleted"]}'

GET /api/v1/webhooks

Lists current tenant webhook endpoints.

PATCH /api/v1/webhooks/{id}

Updates url/events/is_active.

DELETE /api/v1/webhooks/{id}

Deletes webhook.

Every webhook request body:

{
  "event": "email.received",
  "timestamp": 1777290021,
  "data": {
    "email_id": 101,
    "mailbox_id": 10
  }
}

Headers:

• check_circleX-Webhook-Signature: HMAC_SHA256(timestamp + "." + raw_json_payload, webhook_secret)
• check_circleX-Webhook-Timestamp: unix timestamp

Delivery is queued and retried with exponential backoff.