Signatures

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET /api/v1/signatures

List my signatures

The signatures of the signed-in member, then those of the organisation. The order is the contract: a client taking the first default finds its own, not the house one.

Access — Member session or API key with scope profile:read.

Responses

200 — The signatures.

Field	Type	Required
signatures	object[]	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "signatures": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "scope": { "type": "string", "enum": [ "member", "org" ] },
          "name": { "type": "string" },
          "bodyText": { "type": "string" },
          "bodyHtml": { "type": "string" },
          "isDefault": { "type": "boolean" },
          "createdAt": { "type": "string" },
          "updatedAt": { "type": "string" }
        },
        "required": [
          "id",
          "scope",
          "name",
          "bodyText",
          "bodyHtml",
          "isDefault",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "signatures" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

POST /api/v1/signatures

Create a signature

The HTML body is sanitised on write. scope: "org" is reserved to administrators. A name already used by the same owner is refused.

Access — Member session or API key with scope profile:write.

Request body (application/json)

Field	Type	Required
name	string	yes
bodyText	string	no
bodyHtml	string	no
scope	"member" | "org"	no
isDefault	boolean	no

JSON Schema

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "bodyText": { "default": "", "type": "string", "maxLength": 10000 },
    "bodyHtml": { "default": "", "type": "string", "maxLength": 50000 },
    "scope": { "default": "member", "type": "string", "enum": [ "member", "org" ] },
    "isDefault": { "type": "boolean" }
  },
  "required": [ "name" ]
}

Responses

201 — The signature.

Field	Type	Required
signature	object	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "signature": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "scope": { "type": "string", "enum": [ "member", "org" ] },
        "name": { "type": "string" },
        "bodyText": { "type": "string" },
        "bodyHtml": { "type": "string" },
        "isDefault": { "type": "boolean" },
        "createdAt": { "type": "string" },
        "updatedAt": { "type": "string" }
      },
      "required": [
        "id",
        "scope",
        "name",
        "bodyText",
        "bodyHtml",
        "isDefault",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [ "signature" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request, auth.forbidden, contacts.duplicate_signature_name. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

PUT /api/v1/signatures/{id}

Update a signature

A partial replacement: only the given fields change. A signature outside the member’s scope is a 404, never a 403; organisation signatures are only writable by administrators.

Access — Member session or API key with scope profile:write.

Parameters

Name	In	Type	Required
id	path	string	yes

Request body (application/json)

Field	Type	Required
name	string	no
bodyText	string	no
bodyHtml	string	no
isDefault	boolean	no

JSON Schema

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
    "bodyText": { "type": "string", "maxLength": 10000 },
    "bodyHtml": { "type": "string", "maxLength": 50000 },
    "isDefault": { "type": "boolean" }
  }
}

Responses

200 — The signature, updated.

Field	Type	Required
signature	object	yes

Same schema as POST /api/v1/signatures.

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request, contacts.not_found, contacts.duplicate_signature_name. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

DELETE /api/v1/signatures/{id}

Delete a signature

Address-book entries that referenced it lose the reference; they are not deleted with it.

Access — Member session or API key with scope profile:write.

Parameters

Name	In	Type	Required
id	path	string	yes

Responses

204 — Deleted.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — contacts.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET /api/v1/webmail/signatures

List my signatures

WARNING

Deprecated.

The signatures of the signed-in member, then those of the organisation. The order is the contract: a client taking the first default finds its own, not the house one.

Access — Member session or API key with scope profile:read.

Responses

200 — The signatures.

Field	Type	Required
signatures	object[]	yes

Same schema as GET /api/v1/signatures.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

POST /api/v1/webmail/signatures

Create a signature

WARNING

Deprecated.

The HTML body is sanitised on write. scope: "org" is reserved to administrators. A name already used by the same owner is refused.

Access — Member session or API key with scope profile:write.

Request body (application/json)

Field	Type	Required
name	string	yes
bodyText	string	no
bodyHtml	string	no
scope	"member" | "org"	no
isDefault	boolean	no

Same schema as POST /api/v1/signatures.

Responses

201 — The signature.

Field	Type	Required
signature	object	yes

Same schema as POST /api/v1/signatures.

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.

Error codes — request.bad_request, auth.forbidden, contacts.duplicate_signature_name. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

PUT /api/v1/webmail/signatures/{id}

Update a signature

WARNING

Deprecated.

A partial replacement: only the given fields change. A signature outside the member’s scope is a 404, never a 403; organisation signatures are only writable by administrators.

Access — Member session or API key with scope profile:write.

Parameters

Name	In	Type	Required
id	path	string	yes

Request body (application/json)

Field	Type	Required
name	string	no
bodyText	string	no
bodyHtml	string	no
isDefault	boolean	no

Same schema as PUT /api/v1/signatures/{id}.

Responses

200 — The signature, updated.

Field	Type	Required
signature	object	yes

Same schema as POST /api/v1/signatures.

400 — The request does not match its schema.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — request.bad_request, contacts.not_found, contacts.duplicate_signature_name. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

DELETE /api/v1/webmail/signatures/{id}

Delete a signature

WARNING

Deprecated.

Address-book entries that referenced it lose the reference; they are not deleted with it.

Access — Member session or API key with scope profile:write.

Parameters

Name	In	Type	Required
id	path	string	yes

Responses

204 — Deleted.

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

Error codes — contacts.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.