Mailbox Performance

Aggregate reply and close performance for a mailbox over a date range. Async, paginated, supports field groups.

Returns mailbox-level reply and close performance, aggregated across all users in the mailbox and grouped by time period. Mirrors the Mailbox Performance and Mailbox Closed Performance reports in Emailgistics Admin.

POST/api/v1/reports/mailboxPerformance

Auth: Bearer API key — requires reporting scope
Async: Yes — see Result envelope and async polling
Pagination: Yes — see Pagination

Authorization

The API key must include the reporting scope and have the requested mailboxId in its mailbox allowlist. A missing scope returns 403; a mailboxId outside the allowlist returns 404.

Query parameters

fieldGroup?stringdefault replyData

Comma-separated list of field groups to include. See Field groups.

max?integerdefault 50

Maximum result rows per page. Capped at 500.

starting_after?string

Cursor — return rows whose id is greater than this. Mutually exclusive with ending_before.

ending_before?string

Cursor — return rows whose id is less than this. Mutually exclusive with starting_after.

Body parameters

mailboxIdstring

The mailbox to report on. Must be in the API key’s mailbox allowlist.

startstring (ISO 8601 datetime)

Start of the report range. If you include a timezone (Z or +05:30), it’s ignored — the timestamp is interpreted in the mailbox’s time zone.

endstring (ISO 8601 datetime)

End of the report range, in the mailbox’s time zone.

period"hour" | "day" | "week" | "month"

Time period to group results by. Results always start with the period containing start and end with the period containing end.

Field groups

`replyData` (default)

Mailbox-aggregate reply performance.

idstring

Cursor used by pagination.

startDateTimestring (ISO 8601 datetime)

Start of the period this row covers.

receivedinteger

Number of incoming messages received. Always present in the response (regardless of which field groups are requested).

initiatedinteger

Outgoing messages started by the mailbox (not replies).

initialRepliesinteger

Number of initial replies sent from the mailbox.

additionalRepliesinteger

Subsequent replies on the same conversation.

averageMailboxInitialReplyTimenumber

Average mailbox reply time, in minutes.

averageElapsedInitialReplyTimenumber

Average elapsed reply time, in minutes.

insideReplySlainteger

Number of initialReplies that met their SLA.

replyConversationsinteger

Distinct conversations involved in the replies.

newConversationsinteger

Conversations started in this period.

existingConversationsinteger

Conversations from earlier periods that had activity in this one.

`closeData`

Mailbox-aggregate close performance.

idstring

Cursor used by pagination.

startDateTimestring (ISO 8601 datetime)

Start of the period this row covers.

receivedinteger

Number of incoming messages received. Always present in the response.

closedArchivedinteger

Messages closed by archiving.

closedDeletedinteger

Messages closed by deletion.

closedJunkinteger

Messages closed by being marked Junk.

closedSentItemsinteger

Messages closed by being moved to Sent Items.

averageMailboxCloseTimenumber

Average mailbox close time, in minutes.

averageElapsedCloseTimenumber

Average elapsed close time, in minutes.

insideClosedSlainteger

Count of closed messages that met their SLA.

Request

curl -X POST 'https://c1.emailgistics.com/api/v1/reports/mailboxPerformance?fieldGroup=replyData,closeData' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "mailboxId": "af412a6c-657f-445b-892c-b6b1fa41ad1b",
    "start":     "2026-01-01T00:00:00",
    "end":       "2026-05-01T00:00:00",
    "period":    "month"
  }'

{
  "mailboxId": "af412a6c-657f-445b-892c-b6b1fa41ad1b",
  "start":     "2026-01-01T00:00:00",
  "end":       "2026-05-01T00:00:00",
  "period":    "month"
}

Response

This endpoint is asynchronous. The first response often returns status: "running". Poll the URL in _links.self until status: "done". See Result envelope and async polling for the full lifecycle and recommended cadence.

Initial response — `status: "running"`

Returned immediately when the report is queued.

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/8f9a1b2c-...?max=50", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxPerformance", "method": "POST", "body": { "parameters": { "mailboxId": "af412a6c-...", "start": "2026-01-01T00:00:00", "end": "2026-05-01T00:00:00", "period": "month" } } }
  },
  "status":   "running",
  "progress": 30,
  "result":   { "total": null, "data": [], "timeZone": "America/New_York" }
}

Poll `_links.self`

Use exponential backoff starting at 2 seconds, capped at 30 seconds. Result IDs expire 24 hours after creation; calls to expired result IDs return 404.

Final response — `status: "done"`

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/8f9a1b2c-...?max=50", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxPerformance", "method": "POST", "body": { "parameters": { "mailboxId": "af412a6c-...", "start": "2026-01-01T00:00:00", "end": "2026-05-01T00:00:00", "period": "month" } } }
  },
  "status":   "done",
  "progress": 100,
  "result": {
    "total": 4,
    "dataCutoffTimestamp": "2026-05-01T08:14:00.0",
    "timeZone": "America/New_York",
    "data": [
      {
        "id":                             "10001",
        "startDateTime":                  "2026-01-01T00:00:00",
        "received":                       2841,
        "initialReplies":                 1923,
        "additionalReplies":              612,
        "averageMailboxInitialReplyTime": 88.1,
        "averageElapsedInitialReplyTime": 142.5,
        "insideReplySla":                 1791,
        "replyConversations":             1842,
        "newConversations":               2103,
        "existingConversations":          738,
        "closedArchived":                 1502,
        "closedDeleted":                  187,
        "closedJunk":                     43,
        "closedSentItems":                912,
        "averageMailboxCloseTime":        198.4,
        "averageElapsedCloseTime":        267.2,
        "insideClosedSla":                1438
      }
    ]
  }
}

More examples

Hourly breakdown for a single day, replies only

Useful for staffing analysis. Hour grouping over a 24-hour window returns 24 rows.

curl -X POST 'https://c1.emailgistics.com/api/v1/reports/mailboxPerformance' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "mailboxId": "af412a6c-657f-445b-892c-b6b1fa41ad1b",
    "start":     "2026-04-15T00:00:00",
    "end":       "2026-04-16T00:00:00",
    "period":    "hour"
  }'

{
  "_links": {
    "self":   { "href": "https://c1.emailgistics.com/api/v1/reports/results/c2d3e4f5-...?max=50", "method": "GET" },
    "origin": { "href": "https://c1.emailgistics.com/api/v1/reports/mailboxPerformance", "method": "POST", "body": { "parameters": { "mailboxId": "af412a6c-...", "start": "2026-04-15T00:00:00", "end": "2026-04-16T00:00:00", "period": "hour" } } }
  },
  "status":   "done",
  "progress": 100,
  "result": {
    "total": 24,
    "dataCutoffTimestamp": "2026-04-16T00:00:00.0",
    "timeZone": "America/New_York",
    "data": [
      { "id": "10101", "startDateTime": "2026-04-15T08:00:00", "received": 47, "initialReplies": 31, "additionalReplies": 8,  "averageMailboxInitialReplyTime": 22.4 },
      { "id": "10102", "startDateTime": "2026-04-15T09:00:00", "received": 92, "initialReplies": 64, "additionalReplies": 18, "averageMailboxInitialReplyTime": 18.1 },
      { "id": "10103", "startDateTime": "2026-04-15T10:00:00", "received": 73, "initialReplies": 51, "additionalReplies": 14, "averageMailboxInitialReplyTime": 19.7 }
    ]
  }
}

Pagination

If the result set spans multiple pages, the response includes _links.next and/or _links.prev. Follow them to retrieve adjacent pages — see Pagination.

Errors

Status	When
`400`	Body fails validation — missing required field, invalid `period`, or `start` after `end`.
`401`	API key missing, malformed, or expired.
`403`	Key is missing the `reporting` scope.
`404`	`mailboxId` is not in the key’s mailbox allowlist (or doesn’t exist — the two cases are indistinguishable).
`429`	Rate limit exceeded — see Rate limits.
`5xx`	Transient server error.

Error bodies follow the standard shape — see Errors.

Mailbox User Performance — the same data broken out per user.
Poll report results — the polling endpoint used here.
Result envelope and async polling
Field groups and includeDetails

Mailbox Performance

On this page