Mailboxes

All endpoints require authentication. See Authentication for details.

Every request should include these headers:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

IMAP configuration (host, port, encryption, username, and password) is managed per-account in the admin panel. To set up or update IMAP credentials, edit the account in the Filament admin area and ensure the Mail toggle is enabled.


GET /api/{account}/mailbox

Returns IMAP folders for the account.

Parameter Type Description
account integer Account ID
curl -s https://your-domain.com/api/1/mailbox \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response (200)

{
  "data": [
    {
      "path": "INBOX",
      "name": "INBOX"
    },
    {
      "path": "INBOX.Sent",
      "name": "Sent"
    },
    {
      "path": "INBOX.Drafts",
      "name": "Drafts"
    }
  ]
}

Error Responses

Status Reason
401 Unauthenticated
404 Account not found, does not belong to you, or mail is not enabled
503 Unable to connect to mailbox (IMAP failure)

GET /api/{account}/mailbox/{folder}/messages

Returns paginated message summaries for a folder.

Parameter Type Description
account integer Account ID
folder string Folder path (e.g. INBOX)
page integer Page number (default: 1)
per_page integer Results per page (default: 15, max: 50)
curl -s "https://your-domain.com/api/1/mailbox/INBOX/messages?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response (200)

{
  "data": [
    {
      "uid": 42,
      "subject": "Meeting tomorrow",
      "from": {
        "address": "[email protected]",
        "name": "Alice Smith"
      },
      "to": [
        {
          "address": "[email protected]",
          "name": "You"
        }
      ],
      "date": "2025-01-15T10:30:00+00:00",
      "has_attachments": false
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 42
  }
}

Error Responses

Status Reason
401 Unauthenticated
404 Account not found, or folder not found
503 Unable to connect to mailbox (IMAP failure)

GET /api/{account}/mailbox/{folder}/messages/{uid}

Returns a single message with full body content.

Parameter Type Description
account integer Account ID
folder string Folder path (e.g. INBOX)
uid integer Message UID
curl -s https://your-domain.com/api/1/mailbox/INBOX/messages/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response (200)

{
  "data": {
    "uid": 42,
    "subject": "Meeting tomorrow",
    "from": {
      "address": "[email protected]",
      "name": "Alice Smith"
    },
    "to": [
      {
        "address": "[email protected]",
        "name": "You"
      }
    ],
    "date": "2025-01-15T10:30:00+00:00",
    "has_attachments": true,
    "cc": [],
    "text": "Hi, just a reminder about our meeting tomorrow at 10am.",
    "html": "<p>Hi, just a reminder about our meeting tomorrow at 10am.</p>",
    "attachment_count": 2
  }
}

The attachment_count field tells you how many attachments are available on the message. Use the List Attachments endpoint to retrieve their metadata and the Download Attachment endpoint to download their contents.

Error Responses

Status Reason
401 Unauthenticated
404 Account not found, folder not found, or message not found
503 Unable to connect to mailbox (IMAP failure)

GET /api/{account}/mailbox/{folder}/messages/{uid}/attachments

Returns a JSON array of attachment metadata for a message.

Parameter Type Description
account integer Account ID
folder string Folder path (e.g. INBOX)
uid integer Message UID
curl -s https://your-domain.com/api/1/mailbox/INBOX/messages/42/attachments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Success Response (200)

{
  "data": [
    {
      "index": 0,
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "extension": "pdf",
      "content_id": null
    },
    {
      "index": 1,
      "filename": "logo.png",
      "content_type": "image/png",
      "extension": "png",
      "content_id": "<[email protected]>"
    }
  ]
}

Error Responses

Status Reason
401 Unauthenticated
404 Account not found, does not belong to you, mail is not enabled, folder not found, or message not found
503 Unable to connect to mailbox (IMAP failure)

GET /api/{account}/mailbox/{folder}/messages/{uid}/attachments/{index}

Streams a single attachment as a binary download. The response body is the raw file content, not JSON.

Parameter Type Description
account integer Account ID
folder string Folder path (e.g. INBOX)
uid integer Message UID
index integer 0-based attachment index (from the list attachments response)
curl -s https://your-domain.com/api/1/mailbox/INBOX/messages/42/attachments/0 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o invoice.pdf

Success Response (200)

The response is a binary stream. The Content-Type header matches the attachment's MIME type (e.g. application/pdf, image/png) and Content-Disposition: attachment is set with the original filename.

Error Responses

Status Reason
401 Unauthenticated
404 Account not found, does not belong to you, mail is not enabled, folder not found, message not found, or index out of bounds
503 Unable to connect to mailbox (IMAP failure)