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

# Workspace Data

Beyond email validation, the API gives you access to the data behind your Allegrow workspace — connected mailboxes, sender reputation, sending domains, Safety Net mailboxes and sequences, and users — so you can feed it into your own dashboards, BI tools, or spreadsheets. This page covers the conventions shared by the [Connected Mailboxes](/reference/connected-mailboxes-overview), [Connected Domains](/reference/connected-domains-overview), [Users](/reference/users-overview), and [Safety Net](/reference/safety-net-overview) endpoints — each of those sections opens with an overview explaining what the resource is if you use Allegrow through the API only.

Every endpoint authenticates with the same `x-api-key` you already use for validation and never consumes validation credits. Most endpoints are read-only `GET`s; a small set of writes — [inviting users](/reference/invite-user) and toggling the Safety Net on [mailboxes](/reference/update-safety-net-mailbox) and [sequences](/reference/update-safety-net-sequence) — mirror actions from the app and enforce the same rules. Where the app requires a role permission — inviting users and toggling sequences — the API requires the key's creator to hold it and returns `403` otherwise; the mailbox toggle, like its in-app switch, needs no special role.

<br />

## Two Kinds of Mailboxes

The API exposes two distinct mailbox populations. Keeping them apart avoids most confusion:

* **Connected mailboxes** ([List Connected Mailboxes](/reference/list-connected-mailboxes)) — mailboxes your team has connected to Allegrow. These are the mailboxes with connection status, an owner, and sender reputation.
* **Safety Net mailboxes** ([List Safety Net Mailboxes](/reference/list-safety-net-mailboxes)) — mailboxes synced from your sales-engagement platform (Outreach or Salesloft). The sync brings in every mailbox present in that platform; `activated` tells you which ones have the Safety Net switched on. Many teams intentionally activate only a subset.

A user can appear in both lists, in either, or in neither.

<br />

## Reputation

Reputation is a 0–100 score reflecting how reliably a mailbox's email reaches the primary inbox — the same figures shown in the Allegrow app:

* **List endpoints** return an *average* over a named window. [List Connected Mailboxes](/reference/list-connected-mailboxes) takes `reputationRange` (default `last30Days`) and echoes the resolved window in the response — the same projection as the in-app leaderboard.
* **Detail endpoints** return the *latest daily value* (`currentReputation` / `reputation`) plus a day-by-day `history` series, windowed by `startDate`/`endDate` (default: the last 90 days).

`null` reputation means no data in the window — typically a freshly connected mailbox (reputation starts accruing a few days after connection).

<br />

## Conventions

* **Pagination** — every list takes `limit` (1–1000, default 50) and `offset`, and returns `total` for the matching result set. Mailbox and user lists are sorted by `email` ascending, domains by `domain`, and sequences by `name` then `crmSequenceId` (a deterministic order, so offset pages neither skip nor repeat entries while the data is unchanged). For a full-workspace snapshot, request `limit=1000` in one call rather than stitching offset pages — each page is computed independently, so rows can shift between pages if mailboxes connect or disconnect mid-pull. The exception is [Safety Net sequences](/reference/list-safety-net-sequences), where the largest workspaces exceed a single page by design and paging through offsets is the intended usage.
* **Filters** — lists filter server-side: `connectionStatus` on mailboxes, `status` on users, `activated` on Safety Net mailboxes, and `service`/`activated` on Safety Net sequences. `total` always reflects the filter, so a filtered call with `limit=1` is a cheap headline metric (e.g. "how many mailboxes need reconnection").
* **Email uniqueness** — the mailbox, user, and Safety Net mailbox lists contain at most one entry per email address; duplicate source rows (e.g. case variants from a CRM sync) are merged before the response is built. Sequences are per owner and sequence, so an owner appears once per sequence they own.
* **Ids in URLs** — mailbox, user, and Safety Net detail endpoints are keyed by an opaque `id` (a UUID); fetch ids from the list endpoints. Connected-domain detail is keyed by the `domainName` itself. Ids are stable for the lifetime of the resource; reconnecting a mailbox issues a new id. Sequences additionally carry a `crmSequenceId` in the body for cross-referencing them in Outreach or Salesloft.
* **Timestamps** — ISO 8601, UTC. Dates are `YYYY-MM-DD`.
* **Response keys** — always alphabetically ordered.
* **Errors** — invalid parameters return `400` with an `error` message; unknown resources return `404`. Writes can additionally return `403` (the key's user lacks the required permission) or `409` (the request conflicts with workspace state — for example inviting an email that already belongs to an active user, or running out of seats). If a dependent Allegrow service is briefly unavailable you'll get a `503` with a `Retry-After` header — retry after the suggested wait. A missing API key returns `401`, an invalid one `403`, and exceeding your rate limit `429`.
* **Rate limit** — requests count against the same per-second rate limit as your validation API calls (they never consume validation credits or monthly quota). See [Rate Limits](/reference/rate-limits).

<br />

## Quick Tour

Pull the reputation leaderboard for the last 7 days:

```bash
curl "https://api.allegrow.co/v1/connected-mailboxes?reputationRange=last7Days" \
  -H "x-api-key: YOUR_API_KEY"
```

Fetch one mailbox's daily reputation history for a specific window (using its `id` from the list above):

```bash
curl "https://api.allegrow.co/v1/connected-mailboxes/550e8400-e29b-41d4-a716-446655440000?startDate=2026-07-01&endDate=2026-08-01" \
  -H "x-api-key: YOUR_API_KEY"
```

List only the Safety Net mailboxes that are activated:

```bash
curl "https://api.allegrow.co/v1/safety-net-mailboxes?activated=true" \
  -H "x-api-key: YOUR_API_KEY"
```

Count the mailboxes that need reconnecting (read `total`):

```bash
curl "https://api.allegrow.co/v1/connected-mailboxes?connectionStatus=credentials_error&limit=1" \
  -H "x-api-key: YOUR_API_KEY"
```

Find users who haven't connected a mailbox yet (look for `"mailboxes": []`):

```bash
curl "https://api.allegrow.co/v1/users" \
  -H "x-api-key: YOUR_API_KEY"
```

Switch the Safety Net off for a sequence (using its `id` from the sequences list):

```bash
curl -X PATCH "https://api.allegrow.co/v1/safety-net-sequences/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activated": false}'
```