Skip to content
Facteur for developers

Open an inbox

POST
/v1/workspaces/{slug}/inboxes
curl --request POST \
  --url https://api.facteur.eu/v1/workspaces/example/inboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example" }'

The response carries domain: the address mail for this inbox is sent to. It is derived from the inbox id, and neither ever changes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
slug
required
string

The workspace slug.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
description
string
Examplegenerated
{
  "name": "example",
  "description": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

The inbox, and the address it receives at.

Media typeapplication/json
object
id
required
string
name
required
string
description
required
string
domain
required

Send mail here.

string
retentionDays
required
integer
workspace
object
slug
string
name
string
Examplegenerated
{
  "id": "example",
  "name": "example",
  "description": "example",
  "domain": "example",
  "retentionDays": 1,
  "workspace": {
    "slug": "example",
    "name": "example"
  }
}

400

Section titled “400”

NAME_REQUIRED, DESCRIPTION_INVALID, or INVALID_JSON.

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_LIMIT_REACHED — the plan includes fewer inboxes than this would make. Counted for the organization, not for the workspace.

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”

WORKSPACE_NOT_FOUND.

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