List every file

GET/api/v1/mailbox/files

Requires amailbox token— it acts as one mailbox holder, not as the organization.

Every attachment in the mailbox, as one list you can search and filter: by name (q), kind, person, direction (received or sent), date range (since, until), size, and sort. Page with cursor: pass back next_cursor until it is null.

Errors

Status	When
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.

Parameters

Name	In	Type
`q`	query	string
`kind`	query	string
`person`	query	string
`direction`	query	string
`since`	query	string
`until`	query	string
`min_size`	query	string
`max_size`	query	string
`sort`	query	string
`cursor`	query	integer
`limit`	query	integer

Request

GET/api/v1/mailbox/files

curl -X GET 'https://courier.mailyte.com/api/v1/mailbox/files' \
  -H 'Authorization: Bearer MAILBOX_TOKEN'

const response = await fetch('https://courier.mailyte.com/api/v1/mailbox/files', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer MAILBOX_TOKEN',
  },
});
const { data } = await response.json();

import requests
response = requests.get(
    "https://courier.mailyte.com/api/v1/mailbox/files",
    headers={"Authorization": "Bearer MAILBOX_TOKEN"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('MAILBOX_TOKEN')
    ->get('https://courier.mailyte.com/api/v1/mailbox/files');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://courier.mailyte.com/api/v1/mailbox/files")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer MAILBOX_TOKEN"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

Successful Response

dataobject
- filesarray<object>
  - idstring
  - message_idstring
  - folderstring
  - directionstringreceived | sent
  - indexinteger
  - namestring
  - typestring
  - kindstring
    images, pdfs, documents, spreadsheets, presentations, archives, media or other.
  - sizeinteger
  - subjectstring
  - fromobject
    - namestring or null
    - emailstringrequired
  - toobject
    - namestring or null
    - emailstringrequired
  - received_atstring or null
- next_cursorinteger or null
- totalinteger
- total_messagesinteger
- scannedinteger

200application/json

{
  "type": "success",
  "msg": "Files retrieved successfully",
  "data": {
    "files": [
      {
        "id": "INBOX:4821/1",
        "message_id": "INBOX:4821",
        "folder": "INBOX",
        "direction": "received",
        "index": 1,
        "name": "q3-figures.pdf",
        "type": "application/pdf",
        "kind": "pdfs",
        "size": 248311,
        "subject": "Re: the quarterly numbers",
        "from": {
          "name": "Tunde Bello",
          "email": "tunde@example.com"
        },
        "to": {
          "name": "Ada Obi",
          "email": "ada@yourdomain.com"
        },
        "received_at": "2026-10-11T09:14:02+00:00"
      }
    ],
    "next_cursor": 50,
    "total": 316,
    "total_messages": 1696,
    "scanned": 1696
  }
}

Returned inside the standard envelope.

Errors

Status	When
`401`	No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
`403`	The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
`422`	Validation Error

Every status, with what causes it and what to do, is on the error reference.