For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • FreeCustom.Email API
        • GETList inboxes
        • POSTRegister an inbox
          • DELUnregister an inbox
            • GETList messages
LogoLogo
FreeCustom.Email APIV1InboxesInboxMessages

List messages

||View as Markdown|
GET
https://api2.freecustom.email/v1/inboxes/:inbox/messages
GET
/v1/inboxes/:inbox/messages
$curl -G https://api2.freecustom.email/v1/inboxes/%7B%7Bmailbox%7D%7D/messages \
>     -H "Authorization: Bearer <token>" \
>     -d limit=20 \
>     -d before=string
1{
2  "success": true,
3  "data": {
4    "inbox": "string",
5    "messages": [
6      {
7        "id": "string",
8        "from": "string",
9        "subject": "string",
10        "date": "2025-01-04T10:08:40.720Z",
11        "has_attachment": false,
12        "otp": "string",
13        "verification_link": "string"
14      },
15      {
16        "id": "string",
17        "from": "string",
18        "subject": "string",
19        "date": "1955-01-15T16:03:05.610Z",
20        "has_attachment": false,
21        "otp": "string",
22        "verification_link": "string"
23      }
24    ],
25    "count": 3338,
26    "has_more": false
27  }
28}
Returns a paginated list of messages received in the specified inbox, ordered newest first. **Path parameters:** - `:inbox` — URL-encoded inbox address (e.g., `test%40domain.com`) **Query parameters:** - `limit` *(optional)* — Number of messages to return per page. Default: `20`. Max: `100`. - `before` *(optional)* — Cursor for pagination. Pass the `id` of the last message from the previous page to fetch the next page. **Response fields (per message):** - `id` — Unique message identifier - `from` — Sender address - `subject` — Email subject line - `receivedAt` — ISO 8601 timestamp - `otp` — `"__DETECTED__"` if an OTP was found but plan is below Growth; full value on Growth+ **Behaviour:** - Returns an empty array `[]` if no messages have been received. - Use the `before` cursor with the last `id` in the response to paginate through older messages. **Plan:** All plans (Free and above). Full OTP value in listing requires Growth plan or higher.
Was this page helpful?
Previous

Unregister an inbox

Next

Get a message

Built with

Returns a paginated list of messages received in the specified inbox, ordered newest first.

Path parameters:

  • :inbox — URL-encoded inbox address (e.g., test%40domain.com)

Query parameters:

  • limit (optional) — Number of messages to return per page. Default: 20. Max: 100.
  • before (optional) — Cursor for pagination. Pass the id of the last message from the previous page to fetch the next page.

Response fields (per message):

  • id — Unique message identifier
  • from — Sender address
  • subject — Email subject line
  • receivedAt — ISO 8601 timestamp
  • otp — "__DETECTED__" if an OTP was found but plan is below Growth; full value on Growth+

Behaviour:

  • Returns an empty array [] if no messages have been received.
  • Use the before cursor with the last id in the response to paginate through older messages.

Plan: All plans (Free and above). Full OTP value in listing requires Growth plan or higher.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

inboxstringRequired

Query parameters

limitintegerOptional
beforestringOptional

Message ID — returns messages older than this

Response

OK
successboolean
dataobject

Errors

401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error