Skip to content
Facteur for developers

Rename, describe, tag, move, or set a ceiling

PATCH
/v1/inboxes/{id}
curl --request PATCH \
  --url https://api.facteur.eu/v1/inboxes/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "tags": [ "example" ], "workspace": "example", "quota": "example" }'

Every field is optional and applied independently, so a client never has to send back a value it did not touch. Sending none of them is a 400 rather than a no-op — it is almost always a client bug.

The id, and therefore the receiving address, is immutable: it is written into somebody’s test suite.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

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

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Every field optional, applied independently. Sending none of them is a 400.

object
name
string
description

An empty string removes it. Unlike the name, an empty description is accepted.

string
tags
Array<string>
workspace

The slug to move this inbox to. The receiving address does not change.

string
quota

The ceilings this inbox sets for itself.

object | null
Examplegenerated
{
  "name": "example",
  "description": "example",
  "tags": [
    "example"
  ],
  "workspace": "example",
  "quota": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The inbox as it now stands.

Media typeapplication/json
object
id
string
name
string
description
string
tags
Array<string>
workspace
object
slug
string
name
string
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
Examplegenerated
{
  "id": "example",
  "name": "example",
  "description": "example",
  "tags": [
    "example"
  ],
  "workspace": {
    "slug": "example",
    "name": "example"
  },
  "quota": {
    "daily": 1,
    "monthly": {
      "messages": 1,
      "percent": 1
    },
    "onExceed": "example"
  }
}

400

Section titled “400”

INVALID_JSON, NAME_REQUIRED, NAME_TOO_LONG, DESCRIPTION_INVALID, TAGS_INVALID, NOTHING_TO_UPDATE, or one of the quota refusals (LIMIT_NOT_A_WHOLE_NUMBER, LIMIT_IS_ZERO, PERCENTAGE_IS_MONTHLY_ONLY, PERCENTAGE_OUT_OF_RANGE, PERCENTAGE_NEEDS_A_CEILING).

Media typeapplication/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"
  }
}

401

Section titled “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.

Media typeapplication/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"
  }
}

402

Section titled “402”

INBOX_QUOTAS_UNAVAILABLE — raising a ceiling needs a plan that includes per-inbox quotas. Removing one stays open on every plan.

Media typeapplication/json

A refusal that a different plan would not produce. Carries what to change.

object
error
required
object
code
required
string
message
required
string
currentPlan
string
requiredPlan
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "currentPlan": "example",
    "requiredPlan": "example"
  }
}

403

Section titled “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.

Media typeapplication/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

Section titled “404”

INBOX_NOT_FOUND, or WORKSPACE_NOT_FOUND when moving to a workspace the key does not reach.

Media typeapplication/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"
  }
}