The last 50 messages in this inbox

GET

/v1/inboxes/{id}/messages

const url = 'https://api.facteur.eu/v1/inboxes/example/messages';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.facteur.eu/v1/inboxes/example/messages \
  --header 'Authorization: Bearer <token>'

Newest first, and capped at 50 with no pagination. This route answers “what is in the drawer”; to page, to filter, or to wait for a message that has not arrived yet, use POST /v1/messages/search.

Read status on each message before anything derived from the body: a message exists for a few milliseconds after SMTP acknowledgement with no subject, no OTP and no links, because parsing happens after.

Authorizations

bearerAuth
basicAuth

Parameters

Path Parameters

required

string

The inbox identifier — the same string that prefixes its receiving address.

Responses

200

The messages, newest first.

application/json

Array<object>

Read status first. A message accepted over SMTP exists before it is parsed, and a refused one carries no derived fields at all — an absent otp pushes a client to read status rather than assert on a plausible null.

object

required

string

inbox

required

The inbox this arrived in.

string

receivedAt

required

string format: date-time

deliveryMs

How long the message took to reach us.

integer

status

required

received — accepted and stored, not parsed yet. Everything derived from the body is still empty; look again. parsed — everything below is populated. quota_exceeded — refused for want of plan. Nothing was stored or parsed, and the derived fields are absent rather than null.

string

Allowed values: received parsed quota_exceeded

from

required

object

address

string

name

string | null

required

string

sizeBytes

integer

subject

string | null

text

object

body

string | null

html

object

body

string | null

otp

The one-time code found in the message, when there is one. This is the field most suites assert on.

string | null

links

Array<object>

object

key

additional properties

any

codes

Array<object>

object

key

additional properties

any

headers

object

key

additional properties

any

extract

One property per extractor saved on this inbox, keyed by the extractor’s key.

object

key

additional properties

any

error

Present instead of the derived fields when the message was not processed.

object

code

string

Allowed values: PLAN_QUOTA_EXCEEDED INBOX_QUOTA_EXCEEDED

message

string

Example

[
  {
    "status": "received",
    "error": {
      "code": "PLAN_QUOTA_EXCEEDED"
    }
  }
]

401

No usable credential. UNAUTHENTICATED when none was presented, KEY_UNKNOWN, KEY_REVOKED or KEY_EXPIRED when a key was — kept distinct on purpose, because “mint a new one” and “somebody took this away from you” are different facts to whoever is reading a red pipeline.

application/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object

error

required

object

code

required

The stable, machine-readable reason.

string

message

A sentence for whoever is reading the failure. Not part of the contract.

string

Example

{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

403

SCOPE_INSUFFICIENT (the message names the scope this request wanted and the ones the key holds), KEY_CANNOT_REACH (no scope opens this route to a key at all), FORBIDDEN, or one of the stated refusals listed under x-api-key-refusals.

application/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object

error

required

object

code

required

The stable, machine-readable reason.

string

message

A sentence for whoever is reading the failure. Not part of the contract.

string

Example

{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

404

INBOX_NOT_FOUND. An inbox in a workspace the key does not reach answers the same way as one that does not exist — telling the two apart would let anyone map a colleague’s workspaces one request at a time.

application/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object

error

required

object

code

required

The stable, machine-readable reason.

string

message

A sentence for whoever is reading the failure. Not part of the contract.

string

Example

{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}