---
updatedAt: 2026-08-26T10:06:08.000Z
agentTools:
  projectIndex: https://docs.allegrow.co/llms.txt
---

# List Connected Mailboxes

Returns every active mailbox connected to Allegrow in your workspace, with its owner, connection status, and reputation.

The list always contains **all** connected mailboxes — the `reputationRange` parameter never filters the list; it only sets the time window the `reputation` figure is averaged over (the same number the in-app leaderboard shows for that range). A mailbox with no reputation data in the window (for example, one connected in the last few days) still appears, with `reputation: null`.

Results are sorted by `email` ascending and paginate with `limit`/`offset`.


Returns every active mailbox connected to Allegrow in your workspace, with its owner, connection status, and reputation — the API equivalent of the in-app leaderboard.

Two things worth knowing:

* The list always contains **all** connected mailboxes. `reputationRange` never filters the list — it only sets the window the `reputation` average is computed over (default `last30Days`; the response echoes the resolved window).
* A mailbox with no reputation data in the window still appears, with `reputation: null`. Connection visibility is the point: if it's connected, it's listed.

Use `connectionStatus` to slice the list server-side — `?connectionStatus=credentials_error` with `limit=1` turns `total` into a "mailboxes needing attention" metric in one cheap call.

`owner` identifies the user the mailbox belongs to, and is `null` in the rare case the owning user no longer exists in the workspace.

For a single mailbox's day-by-day history, see [Get Connected Mailbox](/reference/get-connected-mailbox).

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Allegrow Workspace API",
    "description": "The Allegrow Workspace API provides read-only, programmatic access to your workspace's connected mailboxes, sender reputation, sending domains, Safety Net mailboxes, and users — the same data shown in the Allegrow app, ready to plug into your own dashboards and BI tooling.\n",
    "version": "1.0.0",
    "contact": {
      "name": "Allegrow Support",
      "email": "support@allegrow.co"
    }
  },
  "servers": [
    {
      "url": "https://api.allegrow.co",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/connected-mailboxes": {
      "get": {
        "summary": "List Connected Mailboxes",
        "description": "Returns every active mailbox connected to Allegrow in your workspace, with its owner, connection status, and reputation.\n\nThe list always contains **all** connected mailboxes — the `reputationRange` parameter never filters the list; it only sets the time window the `reputation` figure is averaged over (the same number the in-app leaderboard shows for that range). A mailbox with no reputation data in the window (for example, one connected in the last few days) still appears, with `reputation: null`.\n\nResults are sorted by `email` ascending and paginate with `limit`/`offset`.\n",
        "operationId": "listMailboxes",
        "tags": [
          "Connected Mailboxes"
        ],
        "parameters": [
          {
            "name": "reputationRange",
            "in": "query",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/ReputationRange"
            },
            "description": "Time window the per-mailbox `reputation` average is computed over. Defaults to `last30Days`. The response echoes the resolved window in its `reputationRange` field.",
            "example": "last30Days"
          },
          {
            "name": "connectionStatus",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Return only mailboxes whose `connectionStatus` matches (e.g. `connected`, `disconnected`, `credentials_error`). Case-insensitive. `total` reflects the filtered count.",
            "example": "credentials_error"
          },
          {
            "$ref": "#/components/parameters/LimitParam"
          },
          {
            "$ref": "#/components/parameters/OffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of connected mailboxes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "limit",
                    "mailboxes",
                    "offset",
                    "reputationRange",
                    "total"
                  ],
                  "properties": {
                    "limit": {
                      "type": "integer",
                      "description": "Page size applied to this response.",
                      "example": 50
                    },
                    "mailboxes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Mailbox"
                      }
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Zero-based index of the first entry returned.",
                      "example": 0
                    },
                    "reputationRange": {
                      "$ref": "#/components/schemas/ReputationRange"
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of connected mailboxes in your workspace (across all pages).",
                      "example": 128
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "reputationRange must be one of: today, yesterday, last7Days, thisWeek, last30Days, lastWeek, lastMonth, thisMonth"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/MissingApiKeyError"
          },
          "403": {
            "$ref": "#/components/responses/InvalidApiKeyError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "503": {
            "description": "A dependent Allegrow service is temporarily unavailable. Retry after the number of seconds in the `Retry-After` header.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Suggested seconds to wait before retrying."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleError"
                },
                "example": {
                  "error": "Service temporarily unavailable"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Allegrow API key"
      }
    },
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 50
        },
        "description": "Page size (1–1000). A single page can hold an entire workspace — for a full snapshot request limit=1000 rather than stitching offset pages, which are computed independently.",
        "example": 50
      },
      "OffsetParam": {
        "name": "offset",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        },
        "description": "Zero-based index of the first entry to return.",
        "example": 0
      }
    },
    "responses": {
      "MissingApiKeyError": {
        "description": "Unauthorized - API key missing from the request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Unauthorized",
              "message": "Unauthorized",
              "statusCode": 401
            }
          }
        }
      },
      "InvalidApiKeyError": {
        "description": "Forbidden - API key invalid or inactive",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Forbidden",
              "message": "Forbidden",
              "statusCode": 403
            }
          }
        }
      },
      "RateLimitError": {
        "description": "Rate limit exceeded. Requests count against the same per-second rate limit as validation API calls.",
        "headers": {
          "Retry-After": {
            "description": "Suggested seconds to wait before retrying",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Too Many Requests",
              "message": "Too Many Requests",
              "statusCode": 429
            }
          }
        }
      }
    },
    "schemas": {
      "ReputationRange": {
        "type": "string",
        "enum": [
          "today",
          "yesterday",
          "last7Days",
          "thisWeek",
          "last30Days",
          "lastWeek",
          "lastMonth",
          "thisMonth"
        ],
        "description": "Named time window for reputation averages. Matches the range picker on the in-app leaderboard.",
        "example": "last30Days"
      },
      "Mailbox": {
        "type": "object",
        "required": [
          "connectedAt",
          "connectionStatus",
          "domain",
          "email",
          "id",
          "owner",
          "provider",
          "reputation",
          "statusUpdatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Opaque identifier for this mailbox — use it with GET /v1/connected-mailboxes/{id}. Stable for the lifetime of the connection; reconnecting a mailbox issues a new id.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "connectedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the mailbox was connected to Allegrow.",
            "example": "2025-11-03T10:00:00Z"
          },
          "connectionStatus": {
            "type": "string",
            "nullable": true,
            "description": "Current connection state. Common values are `connected`, `disconnected`, and `credentials_error`.",
            "example": "connected"
          },
          "domain": {
            "type": "string",
            "description": "Domain portion of the mailbox address.",
            "example": "allegrow.co"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "rep@allegrow.co"
          },
          "owner": {
            "$ref": "#/components/schemas/Owner"
          },
          "provider": {
            "type": "string",
            "nullable": true,
            "description": "Mail provider the mailbox is hosted on.",
            "example": "google"
          },
          "reputation": {
            "type": "number",
            "nullable": true,
            "description": "Average reputation (0–100) over the requested `reputationRange`. `null` when the mailbox has no reputation data in the window.",
            "example": 96.42
          },
          "statusUpdatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When `connectionStatus` last changed.",
            "example": "2026-08-01T00:00:00Z"
          }
        }
      },
      "Owner": {
        "type": "object",
        "nullable": true,
        "description": "The user this mailbox belongs to. `null` when the owning user no longer exists in the workspace.",
        "required": [
          "email",
          "firstName",
          "lastName"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "example": "rep@allegrow.co"
          },
          "firstName": {
            "type": "string",
            "nullable": true,
            "example": "Ada"
          },
          "lastName": {
            "type": "string",
            "nullable": true,
            "example": "Lovelace"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "message",
          "error",
          "statusCode"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "error": {
            "type": "string",
            "description": "Error type"
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code"
          }
        }
      },
      "SimpleError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          }
        }
      }
    }
  }
}
```