List every inbox the key reaches

GET

/v1/inboxes

const url = 'https://api.facteur.eu/v1/inboxes';
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 \
  --header 'Authorization: Bearer <token>'

Across every workspace in the key’s scope. To narrow to one workspace, use GET /v1/workspaces/{slug}/inboxes.

lastMessageAt is the field a test harness reads to answer “did the mail my pipeline just sent land?” without fetching the messages themselves.

Authorizations

bearerAuth
basicAuth

Responses

200

The inboxes, newest first.

application/json

Array<object>

object

required

Also the label that prefixes the receiving address.

string

name

required

string

description

required

Always a string. '' is the one way to say “no description”.

string

domain

required

The address this inbox receives at.

string

createdAt

required

string format: date-time

messageCount

How many messages are stored right now — retention erodes this.

integer

messagesThisMonth

What was consumed this month, from the usage ledger. Not the same figure as messageCount, and the one quotas are metered on.

integer

lastMessageAt

string | null format: date-time

extractorCount

integer

tags

Array<string>

retentionDays

How long messages are kept. 0 means accept, measure, store nothing.

integer

performanceMode

boolean

quota

The ceilings in force. monthly.messages always carries the figure being enforced, whether the customer wrote a number or a share of the plan, so an interface renders it without knowing which. percent is present only when a share is how it was written.

object

daily

Messages accepted per day, or null for no daily ceiling.

integer | null

monthly

object

messages

The ceiling being enforced. Null next to a percent means the plan sells no monthly envelope for that share to apply to, so the rule holds nothing back — shown rather than hidden.

integer | null

percent

Present only when the ceiling was written as a share of the plan.

integer

onExceed

What happens to mail past the ceiling.

string

workspace

object

slug

string

name

string

Example

[
  {
    "domain": "z0cpj88w.inbox.facteur.eu"
  }
]

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"
  }
}