Retrieves the collection of Inbox resources.

GET

/inboxes

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

Authorizations

bearerAuth
ws:read

Responses

200

Inbox collection

application/json

Array<object>

An inbox: what a customer opens to receive mail or SMS, in a workspace.

object

channel

What the inbox receives; it never changes.

string

Allowed values: email sms

createdAt

string format: date-time

description

One line of free text; empty when there is none, never null.

string

domain

string

extractorCount

How many extractors the inbox has.

integer

The identifier of the inbox, 8 characters of lower case letters and digits: the first label of its address, and the key of every route. It never changes.

string

lastMessageAt

string format: date-time

messageCount

How many messages the inbox holds, whatever their status.

integer

messagesThisMonth

What the inbox received on the UTC calendar month, read in the ledger: retention does not erode it, unlike messageCount.

integer

name

string

performanceMode

True when the inbox keeps no content and holds no retention: retentionDays then says nothing about what it keeps.

boolean

quota

The ceilings the inbox sets on itself. Carried on every plan, including those that cannot set one: reading a ceiling is how a customer who left the plan finds the one they have to remove. The sum of the ceilings of an organization is never compared to its envelope.

object

daily

required

The ceiling of a calendar day, in messages, or null when there is none.

integer | null

monthly

required

The monthly ceiling, or null when there is none.

object

messages

required

The ceiling in messages, always the figure in force; null when it is a percentage of a plan that sells no envelope, which holds nothing back.

integer | null

percent

required

The share of the monthly envelope of the plan, from 1 to 100, when the ceiling was written that way; otherwise null.

integer | null

onExceed

required

What the ingester does when a ceiling is reached: refuse the message, or accept it and alert.

string

Allowed values: reject alert

retentionDays

How many days the messages are kept, from the plan the organization had when the inbox was opened.

integer

smsNumber

string

tags

At most 12 tags of at most 32 characters, de-duplicated without regard to case.

Array<string>

workspace

The workspace the inbox lives in, so that a client holding an inbox can build its address without a second request.

object

name

required

string

slug

required

string

Example

[
  {
    "channel": "email",
    "quota": {
      "onExceed": "reject"
    },
    "smsNumber": "+447700900123"
  }
]

401

No key, or a key that is refused. WWW-Authenticate says where to read how to present one.

application/problem+json

A refusal, as RFC 9457 application/problem+json with the code of the register. A code adds the members its rule needs (retryAfter, permission…), so more members than these may come.

object

code

required

The stable code of the refusal. It never changes once shipped.

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND METHOD_NOT_ALLOWED NOT_ACCEPTABLE CONFLICT UNSUPPORTED_MEDIA_TYPE VALIDATION_FAILED RATE_LIMITED SERVICE_UNAVAILABLE INTERNAL_ERROR INVALID_VALUE INVALID_CURSOR ORGANIZATION_LIMIT_REACHED ORGANIZATION_MEMBER_LIMIT_REACHED ORGANIZATION_FOUNDING_IN_PROGRESS ORGANIZATION_ALREADY_MEMBER ORGANIZATION_NAME_EMPTY ORGANIZATION_RENAME_LOCKED ORGANIZATION_RENAME_NOT_LOCKED ORGANIZATION_HAS_PAID_SUBSCRIPTION ORGANIZATION_LAST_OWNER ACCOUNT_DELETION_NOT_CONFIRMED ACCOUNT_HAS_OWN_ORGANIZATIONS ACCOUNT_IS_SOLE_OWNER LOGO_REFUSED LOGO_TOO_LARGE SSO_UNAVAILABLE SSO_PROVIDER_EXISTS SSO_PROVIDER_NOT_FOUND SSO_PROVIDER_REFUSED SSO_SAML_METADATA_INVALID SSO_SAML_METADATA_TOO_LARGE SSO_SAML_CERTIFICATE_EXPIRED SSO_SAML_CERTIFICATE_NOT_YET_VALID SSO_SAML_SHA1_REFUSED SSO_DOMAIN_INVALID SSO_DOMAIN_TAKEN SSO_DOMAIN_NOT_FOUND SSO_DOMAIN_NOT_PROVEN SSO_RESCUE_OWNER_REQUIRED SSO_WITHDRAWAL_EXPIRY_IN_THE_PAST SSO_WITHDRAWAL_EXPIRY_TOO_FAR SSO_WITHDRAWAL_EXPIRY_INVALID SSO_WITHDRAWAL_DOMAIN_NOT_PROVED SSO_DOMAIN_NOT_WITHDRAWN INVITATION_ALREADY_PENDING INVITATION_EXPIRED INVITATION_ALREADY_USED INVITATION_REVOKED INVITATION_ADDRESS_MISMATCH JOIN_LINK_EXPIRED JOIN_LINK_ALREADY_USED JOIN_LINK_REVOKED EMAIL_NOT_SENT WORKSPACE_NOT_FOUND NAME_REQUIRED NAME_TOO_LONG NAME_NOT_SLUGGABLE INVALID_SLUG SLUG_TAKEN TAG_TOO_LONG COLOR_INVALID WORKSPACE_LIMIT_REACHED WORKSPACE_QUOTAS_UNAVAILABLE CANNOT_DELETE_DEFAULT WORKSPACE_OPEN_TO_ORGANIZATION USER_REQUIRED NOT_AN_ORGANIZATION_MEMBER MEMBER_NOT_FOUND QUOTA_INVALID QUOTA_EMPTY ON_EXCEED_UNKNOWN DAILY_IS_INBOX_ONLY LIMIT_NOT_A_WHOLE_NUMBER LIMIT_IS_ZERO PERCENTAGE_OUT_OF_RANGE PERCENTAGE_NEEDS_A_CEILING INBOX_NOT_FOUND DESCRIPTION_INVALID TAGS_INVALID CHANNEL_UNKNOWN NOTHING_TO_UPDATE PERCENTAGE_IS_MONTHLY_ONLY INBOX_LIMIT_REACHED INBOX_QUOTAS_UNAVAILABLE SMS_NUMBER_LIMIT WORKSPACE_NOT_EMPTY MESSAGE_NOT_FOUND CRITERIA_EMPTY CRITERIA_UNKNOWN CRITERIA_INVALID TOO_MANY_WAITS API_DRAINING EXTRACTOR_NOT_FOUND INVALID_KEY KEY_ALREADY_USED PATTERN_REQUIRED INVALID_PATTERN INVALID_SCOPE INVALID_LABEL ATTACHMENT_NOT_FOUND ATTACHMENT_NOT_STORED ATTACHMENT_STORE_UNAVAILABLE SPEND_CAP_NEGATIVE SPEND_CAP_ABOVE_CEILING SPEND_CAP_MISSING SPEND_CAP_UNCHANGED PLAN_IS_UNLIMITED SUBSCRIPTION_ENDED NO_PAY_AS_YOU_GO SUBSCRIPTION_SUSPENDED PAYMENT_EVENT_REFUSED PAYMENT_PROVIDER_UNAVAILABLE CARD_SETUP_NOT_COMPLETE CARD_SETUP_NOT_FOUND CARD_SETUP_WITHOUT_CARD UNKNOWN_PACK PACK_FROZEN_UNTIL_RESUMED PLAN_NOT_PURCHASABLE TERM_REQUIRED ALREADY_SUBSCRIBED NO_SUBSCRIPTION PLAN_UNCHANGED NO_SUBSCRIPTION_TO_CANCEL COMMITMENT_BALANCE_REFUSED NO_CANCELLATION_TO_WITHDRAW BILLING_NAME_REQUIRED ADDRESS_INCOMPLETE COUNTRY_INVALID INVALID_VAT_NUMBER DESTINATION_KIND_UNKNOWN DESTINATION_ADDRESS_INVALID DESTINATION_NAME_INVALID DESTINATION_LOCALE_INVALID TOO_MANY_DESTINATIONS THRESHOLD_INVALID DESTINATION_KIND_IMMUTABLE DESTINATION_TARGET_INVALID DESTINATION_KEY_INVALID DESTINATION_REGION_UNKNOWN DESTINATION_FIELD_NOT_ALLOWED ALERT_CHANNEL_REFUSED ALERT_CHANNEL_UNAVAILABLE WEBHOOK_PORTAL_NOT_READY WEBHOOK_PLATFORM_UNAVAILABLE SUPPORT_KIND_INVALID SUPPORT_SUBJECT_REQUIRED SUPPORT_MESSAGE_REQUIRED FEATURE_REQUEST_SKELETON_EMPTY SUPPORT_TOO_MANY_THREADS SUPPORT_THREAD_NOT_FOUND SUPPORT_THREAD_CLOSED SUPPORT_THREAD_ALREADY_IN_STATE SUPPORT_ATTACHMENT_IDS_INVALID SUPPORT_TOO_MANY_ATTACHMENTS SUPPORT_ATTACHMENT_TOO_LARGE SUPPORT_ATTACHMENT_UNSUPPORTED SUPPORT_ATTACHMENT_REFUSED SUPPORT_TOO_MANY_UPLOADS SUPPORT_STORAGE_FULL SUPPORT_ATTACHMENT_NOT_FOUND SUPPORT_FILTER_INVALID SUPPORT_OUTCOME_INVALID SUPPORT_OUTCOME_NOT_ALLOWED SUPPORT_OUTCOME_NOTE_INVALID SUPPORT_NOT_A_FEATURE_REQUEST STAFF_REASON_INVALID OVERRIDE_EXPIRY_IN_THE_PAST OVERRIDE_EXPIRY_TOO_FAR OVERRIDE_EXPIRY_INVALID STAFF_EXPIRY_INVALID STAFF_EXPIRY_IN_THE_PAST STAFF_EXPIRY_TOO_FAR CAPACITY_OPERATIONS_NOT_POSITIVE CAPACITY_OPERATIONS_TOO_LARGE CAPACITY_GIFT_NOT_FOUND CAPACITY_GIFT_EXPIRED CAPACITY_RETRACTION_TOO_LARGE SPEND_CAP_BOUND_NOT_RAISED SPEND_CAP_BOUND_TOO_HIGH UNKNOWN_CAPABILITY CAPABILITY_OVERRIDE_NOT_FOUND USER_HAS_ORGANIZATIONS USERS_SELECTION_INVALID ASSISTANCE_SESSION_NOT_FOUND ASSISTANCE_SESSION_CLOSED ASSISTANCE_CODE_INVALID ASSISTANCE_TARGET_INVALID SUPPORT_ACCESS_NOT_GIVEN ASSISTANCE_CONSENT_ALREADY_GIVEN ASSISTANCE_CONSENT_NOT_FOUND ASSISTANCE_WRITE_REQUEST_PENDING ASSISTANCE_WRITE_REQUEST_NOT_FOUND EMAIL_DOMAIN_INVALID EMAIL_DOMAIN_ALREADY_BLOCKED EMAIL_DOMAIN_NOT_BLOCKED ASSISTANCE_FORBIDDEN ASSISTANCE_CONSENT_REQUIRED SESSION_CONFINED SIGN_IN_METHOD_NOT_ALLOWED SSO_NEVER_USED SECOND_FACTOR_MISSING SSO_EMAIL_NOT_PROVEN CONSOLE_SSO_REFUSED SUPPORT_CITATIONS_INVALID SUPPORT_CITATION_UNKNOWN AGENT_TOO_MANY_WRITES SUPPORT_ALREADY_REVIEWED SUPPORT_NOTHING_TO_REVIEW AGENT_TOKEN_NOT_FOUND AGENT_TOKEN_REVOKED AGENT_TOKEN_NAME_INVALID AGENT_TOKEN_NAME_TAKEN AGENT_TOKEN_SCOPES_INVALID API_KEY_NOT_FOUND API_KEY_NAME_INVALID API_KEY_PERMISSIONS_INVALID API_KEY_WORKSPACES_INVALID API_KEY_REVOKED WORKSPACE_HAS_ACTIVE_KEYS API_KEY_UNKNOWN API_KEY_EXPIRED API_KEY_PERMISSION_MISSING API_KEY_CANNOT_DELETE_WORKSPACE SMS_COUNTRY_NOT_OPEN SMS_NOTE_TOO_LONG SMS_INBOX_HAS_NUMBER SMS_REQUEST_ALREADY_OPEN SMS_REQUEST_NOT_FOUND SMS_REQUEST_NOT_WITHDRAWABLE SMS_REQUEST_NUMBER_SERVED SMS_REQUEST_NOT_IN_EXPECTED_STATE SMS_REQUEST_INBOX_DELETED SMS_NUMBER_INVALID SMS_NUMBER_TAKEN SMS_NUMBER_NOT_FOUND SMS_EVENT_REFUSED SMS_GATEWAY_UNAVAILABLE

detail

required

English prose for the person who reads the answer. It may be reworded: branch on code.

string

status

required

The HTTP status.

integer

title

required

The name of the HTTP status.

string

type

required

The address of the problem: /errors/<code>.

string

violations

On a body that fails validation, one entry per field.

Array<object>

object

code

required

string

message

required

string

propertyPath

required

string

key

additional properties

any

Example

{
  "code": "BAD_REQUEST",
  "status": 404,
  "title": "Not Found",
  "type": "/errors/INBOX_NOT_FOUND",
  "violations": [
    {
      "code": "BAD_REQUEST"
    }
  ]
}

403

The key does not hold the permission of the operation, or the operation refuses every key.

application/problem+json

A refusal, as RFC 9457 application/problem+json with the code of the register. A code adds the members its rule needs (retryAfter, permission…), so more members than these may come.

object

code

required

The stable code of the refusal. It never changes once shipped.

string

detail

required

English prose for the person who reads the answer. It may be reworded: branch on code.

string

status

required

The HTTP status.

integer

title

required

The name of the HTTP status.

string

type

required

The address of the problem: /errors/<code>.

string

violations

On a body that fails validation, one entry per field.

Array<object>

object

code

required

string

message

required

string

propertyPath

required

string

key

additional properties

any

Example

{
  "code": "BAD_REQUEST",
  "status": 404,
  "title": "Not Found",
  "type": "/errors/INBOX_NOT_FOUND",
  "violations": [
    {
      "code": "BAD_REQUEST"
    }
  ]
}

429

More calls than the key may make in a minute. Retry-After says when to try again.

application/problem+json

A refusal, as RFC 9457 application/problem+json with the code of the register. A code adds the members its rule needs (retryAfter, permission…), so more members than these may come.

object

code

required

The stable code of the refusal. It never changes once shipped.

string

detail

required

English prose for the person who reads the answer. It may be reworded: branch on code.

string

status

required

The HTTP status.

integer

title

required

The name of the HTTP status.

string

type

required

The address of the problem: /errors/<code>.

string

violations

On a body that fails validation, one entry per field.

Array<object>

object

code

required

string

message

required

string

propertyPath

required

string

key

additional properties

any

Example

{
  "code": "BAD_REQUEST",
  "status": 404,
  "title": "Not Found",
  "type": "/errors/INBOX_NOT_FOUND",
  "violations": [
    {
      "code": "BAD_REQUEST"
    }
  ]
}

default

Any refusal: an application/problem+json body whose code says which.

application/problem+json

A refusal, as RFC 9457 application/problem+json with the code of the register. A code adds the members its rule needs (retryAfter, permission…), so more members than these may come.

object

code

required

The stable code of the refusal. It never changes once shipped.

string

detail

required

English prose for the person who reads the answer. It may be reworded: branch on code.

string

status

required

The HTTP status.

integer

title

required

The name of the HTTP status.

string

type

required

The address of the problem: /errors/<code>.

string

violations

On a body that fails validation, one entry per field.

Array<object>

object

code

required

string

message

required

string

propertyPath

required

string

key

additional properties

any

Example

{
  "code": "BAD_REQUEST",
  "status": 404,
  "title": "Not Found",
  "type": "/errors/INBOX_NOT_FOUND",
  "violations": [
    {
      "code": "BAD_REQUEST"
    }
  ]
}