{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/domani-run/json-schema/domani-run-mailbox-connection-schema.json",
  "title": "MailboxConnection",
  "description": "The connection of a mailbox that lives elsewhere (Gmail, or any inbox by forwarding) and its import progress",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/domani-run-openapi.json#/components/schemas/MailboxConnection",
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "mailbox_id": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "gmail",
        "graph",
        "forwarding",
        "imap",
        "jmap"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "error",
        "disconnected"
      ]
    },
    "import_since": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The bound of the first import: no mail received before it is copied"
    },
    "phase": {
      "type": "string",
      "enum": [
        "list",
        "history",
        "paused"
      ],
      "description": "list while the import scan pages through the mail after the bound, history once new mail follows the source's history"
    },
    "paused_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "import_run": {
      "type": [
        "object",
        "null"
      ],
      "description": "The current or last import run of this mailbox",
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "completed"
          ]
        },
        "since": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "until": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "listed": {
          "type": "integer"
        },
        "copied": {
          "type": "integer"
        },
        "to_analyse": {
          "type": "integer"
        },
        "analysed": {
          "type": "integer"
        },
        "listing_done": {
          "type": "boolean"
        },
        "started_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "source_messages_total": {
      "type": [
        "integer",
        "null"
      ],
      "description": "What the source reports for the whole inbox, for scale"
    },
    "last_sync_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_error": {
      "type": [
        "string",
        "null"
      ]
    },
    "backoff_until": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "connected_at": {
      "type": "string",
      "format": "date-time"
    },
    "cost_cap_usd": {
      "type": "number",
      "description": "The model spend allowed per import run, in USD"
    },
    "access": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "read",
        "write"
      ],
      "description": "For a Gmail connection: what the grant allows; write means labels both ways and sending as the person"
    },
    "forwarding": {
      "type": [
        "object",
        "null"
      ],
      "description": "For a connection by forwarding: the forwarding address, what arrived, Gmail's confirmation, the probe, the steps",
      "properties": {
        "address": {
          "type": [
            "string",
            "null"
          ]
        },
        "forwarded": {
          "type": "integer"
        },
        "last_forwarded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "confirmation": {
          "type": [
            "object",
            "null"
          ],
          "description": "Gmail's forwarding confirmation, which is authentication mail: without email:auth_secrets, code and url are null and redacted is true",
          "properties": {
            "code": {
              "type": [
                "string",
                "null"
              ]
            },
            "url": {
              "type": [
                "string",
                "null"
              ]
            },
            "received_at": {
              "type": "string",
              "format": "date-time"
            },
            "redacted": {
              "type": "boolean",
              "description": "True when the code and link are withheld because the caller lacks email:auth_secrets"
            }
          }
        },
        "probe": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "sent_at": {
              "type": "string",
              "format": "date-time"
            },
            "returned_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        "instructions": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "gmail": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "outlook": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "generic": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "guide": {
          "$ref": "#/$defs/ForwardingGuide",
          "nullable": true
        }
      }
    }
  },
  "required": [
    "address",
    "mailbox_id",
    "kind",
    "status",
    "phase",
    "connected_at"
  ],
  "$defs": {
    "ForwardingGuide": {
      "type": "object",
      "description": "The guide of a forwarding connection: the provider the inbox lives at (from the address or its MX), the page where the rule is set, the steps in plain words, whether a confirmation comes back (Gmail's code and link, captured on the connection), and the provider's limits.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "gmail",
            "google_workspace",
            "outlook",
            "microsoft365",
            "fastmail",
            "proton",
            "icloud",
            "yahoo",
            "generic"
          ]
        },
        "name": {
          "type": "string"
        },
        "settings_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "The settings page where the forwarding rule is created, when the provider has a stable one"
        },
        "confirmation": {
          "type": "string",
          "enum": [
            "code_or_link",
            "none"
          ],
          "description": "code_or_link when the provider sends a confirmation the platform captures (Google)"
        },
        "limits": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "paid_plan",
              "rule_based",
              "no_history"
            ]
          }
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "provider",
        "name",
        "settings_url",
        "confirmation",
        "limits",
        "steps"
      ]
    }
  }
}