# listDirectMailLetters

The letters on contacts you can see (Automations → Letters), newest first: `totalCount`, then a page (`limit` default 50, `offset`) of contactName, campaignLabel, workflowName, mode, status (QUEUED, SUBMITTED, MAILED, IN_TRANSIT, DELIVERED, RETURNED, CANCELED, FAILED…), requestedAt, mailedAt, deliveredAt. Narrow with `statuses`, `modes` (LIVE; a TEST account mails and bills nothing) or `search` (a contact or workflow name). The read for "did my letters go out", "how did the last mailer do" and "did anyone answer the mail": totalCount 0 with no narrowing means no letter on a contact you can see was ever mailed (an account setup's test letter is not listed), so say that plainly and never guess. Answers show as the contact's own text, call or email afterwards, and QR scans as the `physicalMail` contact filter.

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "listDirectMailLetters", "variables": {...} }`
- Scope: `READ`
- Type: query
- Idempotency: a read; rejects `Idempotency-Key`
- Rate-limited: no

## Variables

- `limit`: `Int`
- `offset`: `Int`
- `statuses`: `[DirectMailPieceDisplayState!]` (one of `QUEUED`, `SUBMITTING`, `SUBMISSION_UNKNOWN`, `NOT_SUBMITTED`, `SUBMITTED`, `SCHEDULED`, `PRODUCING`, `MAILED`, `IN_TRANSIT`, `RE_ROUTED`, `NEAR_DELIVERY`, `DELIVERED`, `RETURNED`, `CANCELED`, `FAILED`)
- `modes`: `[DirectMailConnectionMode!]` (one of `TEST`, `LIVE`)
- `search`: `String`

## Response (data, an example)

```json
{
  "contactQuery": {
    "directMailLetters": {
      "totalCount": 0,
      "nodes": [
        {
          "id": "<ID>",
          "contactId": "<ID>",
          "contactName": "…",
          "provider": "OPEN_LETTER_CONNECT",
          "campaignLabel": "…",
          "mode": "TEST",
          "status": "QUEUED",
          "refusalReason": "…",
          "requestedAt": "2026-01-01T00:00:00.000Z",
          "mailedAt": "2026-01-01T00:00:00.000Z",
          "deliveredAt": "2026-01-01T00:00:00.000Z",
          "workflowName": "…"
        }
      ]
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "listDirectMailLetters",
    "variables": {}
  }'
```