Reading messages

List messages for an inbox and fetch a single message by ID. Attachment support depends on your plan.

GET /v1/inboxes/{inbox}/messages

Returns messages for the given inbox (newest first). Query params: limit (default 20, max 100), before (message ID for pagination).

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/messages" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Success

json

{
  "success": true,
  "data": {
    "inbox": "mytest@ditapi.info",
    "messages": [
      {
        "id": "msg_01jqz3k4m5n6p7q8r9s0t1u2v3",
        "from": "noreply@github.com",
        "subject": "Your GitHub verification code",
        "date": "2026-03-04T09:55:00.000Z",
        "has_attachment": false,
        "otp": "482931",
        "verification_link": "https://github.com/verify?token=abc123"
      }
    ],
    "count": 1,
    "has_more": false
  }
}

On Free plan, otp and verification_link may be __DETECTED__.

403Inbox not registered

json

{
  "success": false,
  "error": "forbidden",
  "message": "mytest@ditapi.info is not registered on this account."
}

GET /v1/inboxes/{inbox}/messages/{id}

Returns full message body (html, text), metadata, and attachments (if plan allows).

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/messages/msg_abc123" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Success

json

{
  "success": true,
  "data": {
    "id": "msg_01jqz3k4m5n6p7q8r9s0t1u2v3",
    "from": "noreply@github.com",
    "to": "mytest@ditapi.info",
    "subject": "Your GitHub verification code",
    "date": "2026-03-04T09:55:00.000Z",
    "html": "<p>Your code is <strong>482931</strong></p>",
    "text": "Your code is 482931",
    "otp": "482931",
    "verification_link": "https://github.com/verify?token=abc123",
    "has_attachment": true,
    "attachments": [{ "filename": "receipt.pdf", "content_type": "application/pdf", "size_bytes": 204800 }]
  }
}

404Message not found

json

{
  "success": false,
  "error": "not_found",
  "message": "Message msg_abc123 not found in mytest@ditapi.info."
}

GET /v1/inboxes/{inbox}/wait

Wait for a new email to arrive in the specified mailbox (Long Polling). This eliminates the need for rapid polling and reduces request overhead.

Query Params:
timeout: Max seconds to wait (10–60 recommended, default 30).
since: (Optional) Last seen message ID. Return immediately if a newer message exists, otherwise wait.
Plan Requirement: Developer or above.
Billing: High-value endpoint; 1 wait call consumes 10 monthly requests.

curl

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/wait?timeout=45" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200New message received

json

{
  "success": true,
  "message": "New message received",
  "data": {
    "id": "wNp8N0KoV",
    "subject": "Your OTP",
    "from": "service@example.com"
  }
}

200Timeout

json

{
  "success": false,
  "message": "Timeout reached"
}

DELETE /v1/inboxes/{inbox}/messages/{id}

Deletes a single message.

curl

curl -X DELETE "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/messages/msg_abc123" \
  -H "Authorization: Bearer fce_your_api_key"

Responses

200Deleted

json

{
  "success": true,
  "message": "Message msg_abc123 deleted."
}

404Not found

json

{
  "success": false,
  "error": "not_found",
  "message": "Message msg_abc123 not found."
}