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, Connected Domains, Users, and Safety Net 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 GETs; a small set of writes — inviting users and toggling the Safety Net on mailboxes and sequences — 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.

Two Kinds of Mailboxes

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

Connected mailboxes (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) — 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.

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 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).

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, 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.

Quick Tour

Pull the reputation leaderboard for the last 7 days:

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):

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:

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):

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": []):

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):

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}'