listDirectMailLetters
The letters on contacts you can see.
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.
curl https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer $GOLIATH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"operationId": "listDirectMailLetters",
"variables": {}
}'import { GoliathClient } from '@goliath-data/sdk'
const goliath = new GoliathClient({
apiKey: process.env.GOLIATH_API_KEY!,
baseUrl: 'https://server.goliathdata.com',
})
const result = await goliath.account.listDirectMailLetters({})const res = await fetch('https://server.goliathdata.com/api/v1/call', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GOLIATH_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
operationId: 'listDirectMailLetters',
variables: {}
}),
})
const { data, errors } = await res.json()Variables
The example sends only what the schema requires. Some operations also need one of several optional variables (one filter or another, say); the description above says which.
Response
What comes back under data: a list shows as one entry, and a value as its type.
{
"data": {
"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": "…"
}
]
}
}
}
}Errors
unknown_variableA variable the operation does not declare. A typo is refused rather than silently dropped.
unauthorizedNo bearer header, or the key is invalid or revoked.
insufficient_scopeThe key lacks the scope the operation requires.
forbiddenA referenced record does not exist, was deleted, or is outside your organization. The gateway cannot tell those apart.
Behaviour
A read. It rejects an Idempotency-Key header with 400 bad_request.