# mailByRef

query · in the family [Your own session](/reference/your-own-session/)

## What it does

Look up one email the platform sent you by the reference on its last line (ref M-XXXX-XXXX-XXXX) — what fired it, when, and where the request came from.

Requires authentication.

## What happens

A single read of your own mail ledger. A mistyped reference is refused before any read; a reference that belongs to another account reads as not found.

## Who may call it

Capability area: **Your own session** — What every signed-in person may do for themselves — their session, their profile and their own work.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- Cashier
- An API key whose scope allows `api:mailByRef`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `ref` | [String](/types/#scalars) `String!` | yes | No further notes. |

## Returns

[MailLedgerEntry](/types/MailLedgerEntry/) `MailLedgerEntry!` — One email the platform sent to YOUR account. The words derive at read time from the kind + origin.

## Example request

```graphql
query ExampleMailByRef($ref: String!) {
  mailByRef(ref: $ref) {
    ref
    kind
    kindWords
    origin
    originWords
    footerSentence
    subjectId
    eventId
    eventAt
    sentAt
    providerMessageId
    recipientHash
  }
}
```

Variables:

```json
{
  "ref": "<ref>"
}
```

## Example response

```json
{
  "data": {
    "mailByRef": {
      "ref": "01900000-0000-7000-8000-42f484020000",
      "kind": "verification",
      "kindWords": "<kind words>",
      "origin": "office",
      "originWords": "<origin words>",
      "footerSentence": "<footer sentence>",
      "subjectId": "01900000-0000-7000-8000-91fe7ba20000",
      "eventId": "<event id>",
      "eventAt": "2027-01-31T00:00:00.000Z",
      "sentAt": "2027-01-31T00:00:00.000Z",
      "providerMessageId": "<provider message id>",
      "recipientHash": "<recipient hash>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))