MQTT

Secretary supports an optional MQTT entrypoint for triggering rule runs from a message broker.

Enabling MQTT

Set the following environment variables:

environment:
  SECRETARY_MQTT__ENABLED: "true"
  SECRETARY_MQTT__HOST: "mqtt.example.com"
  SECRETARY_MQTT__PORT: "1883"
  SECRETARY_MQTT__USERNAME: "secretary"        # optional
  SECRETARY_MQTT__PASSWORD: "your-password"   # optional
  SECRETARY_MQTT__TLS: "false"

When enabled, Secretary connects to the broker at startup and subscribes to the run topic.

Run topic

Secretary subscribes to the topic defined by SECRETARY_MQTT__RUN_TOPIC (default: secretary/run).

Publish a JSON message to trigger rule processing:

{
  "document": 42,
  "event": "updated",
  "dry_run": false
}

Payload fields

Field	Type	Required	Default	Description
`document`	`int`	✅	—	Paperless-ngx document ID
`event`	`string`		`updated`	Event type: `document_added` or `document_updated`
`dry_run`	`bool`		`true`	Set to `false` to apply changes

Result topic

After processing, Secretary publishes the result to SECRETARY_MQTT__RESULT_TOPIC (default: secretary/result).

The result payload is a JSON object containing the execution traces for all rules that were evaluated.

TLS

Set SECRETARY_MQTT__TLS=true to enable TLS for the broker connection. Secretary uses the system's default CA bundle.

Example: Home Assistant trigger

# configuration.yaml (Home Assistant)
automation:
  - alias: "Process new Paperless document"
    trigger:
      platform: event
      event_type: paperless_document_added
    action:
      service: mqtt.publish
      data:
        topic: secretary/run
        payload: >
          {"document": {{ trigger.event.data.document_id }}, "dry_run": false}