Quickstart

Before you start

You must have an active Stable account an a role that can create API keys.
If you do not have an account, sign up here.
To use the sandbox, see Sandbox.

Create an API key

In the Stable dashboard, go to Settings > API Keys.
Enter a recognizable name for the key.
Create the key.
Copy the key and keep it in a safe place. You will only be shown the key once.

List your addresses

In the API, you'll see addresses referred to as Locations.

Send a request to GET /v1/locations. Put your key in the x-api-key header.

curl https://api.usestable.com/v1/locations \
  -H "x-api-key: $STABLE_API_KEY"

The API will return a list of paginated locations (see Pagination and Filtering):

{
  "pageInfo": {
    "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
    "endCursor": "YXJyYXljb25uZWN0aW9uOjA=",
    "hasNextPage": false,
    "hasPreviousPage": false
  },
  "totalCount": 1,
  "edges": [
    {
      "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
      "node": {
        "id": "3f2b8c1e-5d4a-4e9b-a7c2-9e1f0b6d4a21",
        "status": "active",
        "address": {
          "line1": "1234 Example St",
          "line2": "#4207",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94114"
        },
        "type": "cmra",
        "onboarding": { "status": "complete" },
        "metadata": null
      }
    }
  ]
}

Note these fields in the response:

id is the unique ID for a single Virtual address or Registered Agent. You'll frequently use this ID with other APIs.
address.line2 contains the mailbox number that uniquely identifies the receiving address.
type reflects whether this address is a Virtual address (CMRA) or a Registered Agent
onboarding reflects the current status of the address's USPS Form 1583 authorization.

List your mail

Send a request to GET /v1/mail-items. The first parameter sets the number of items to return.

curl "https://api.usestable.com/v1/mail-items?first=10" \
  -H "x-api-key: $STABLE_API_KEY"

{
  "pageInfo": {
    "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
    "endCursor": "YXJyYXljb25uZWN0aW9uOjk=",
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "totalCount": 132,
  "edges": [
    {
      "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
      "node": {
        "id": "8a6d2f40-1c3b-4b7e-9f55-2d0e7c9a1b38",
        "from": "Internal Revenue Service",
        "imageUrl": "https://…/envelope.jpg?Signature=…",
        "recipients": {
          "line1": { "text": "Acme Inc" },
          …
        },
        "location": { "id": "3f2b8c1e-5d4a-4e9b-a7c2-9e1f0b6d4a21", … },
        "scanDetails": null,
        "clearAt": "2026-11-22T07:59:59.999Z",
        "createdAt": "2026-10-23T15:12:04.000Z",
        …
      }
    },
    …
  ]
}

This response is truncated. See Mail Items for a listing of the complete object.

Note these fields in the response:

locationId: use this to identify which Virtual address received the mail item.
imageUrl: contains the item's Envelope Scan.
scanDetails: in this example, the Document Scan has not been requested. See Scans, OCR, and Summaries to learn more.

Recap

You've successfully created an API key and made your first request! Explore more topics to continue building your integration.

Before you start

Create an API key

List your addresses

List your mail

Recap

What’s Next