> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.usglobalmail.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server. # Resource models The API is organized around a handful of resources. This page is the reference for each resource's shape; the [API Reference](/api/api-reference) has the same fields as an interactive, always-live schema (and the request bodies for create/update endpoints). #### [Mail item](#mail-item) #### [Scan](#scan) #### [Shipment](#shipment) #### [Folder](#folder) #### [Address](#address) #### [Bank account](#bank-account) #### [Account](#account) #### [Mailing address](#mailing-address) > **Note** > > **Ids are strings.** Mail items and folders use **numeric strings** (`"12345"`); scans, shipments, > addresses, bank accounts, and the account use **UUIDs**. Fields marked *nullable* may be `null` or > absent. Timestamps noted *ISO-8601* are `date-time` strings (`2026-07-11T16:04:00Z`). ## Mail item A piece of mail received at your address — the central resource you list, read, organize, and act on. | Field | Type | Notes | | --------------------- | ------- | ------------------------------------------------------------------ | | `id` | string | Mail item id (numeric string). | | `mail_status` | string | Lifecycle status as reported by the mailroom. | | `mail_type` | string | Machine code for the mail type. | | `mail_type_label` | string | Human-readable form of `mail_type` (e.g. "Large Letter"). | | `is_read` | boolean | Whether you've marked it read. | | `sender_name` | string | *nullable.* | | `sender_address` | string | *nullable.* | | `recipient_name` | string | *nullable.* | | `arrival_date` | string | When the item arrived at the facility. *nullable.* | | `envelope_image_url` | string | Photo of the item/envelope. *nullable.* | | `tracking_number` | string | Inbound carrier tracking number, when captured. *nullable.* | | `quarantine_reason` | string | *nullable.* | | `has_storage_charges` | boolean | Whether the item is currently accruing storage charges. | | `weight` | number | Item weight, in pounds. | | `measurement` | object | Item dimensions, in inches — `{ width, height, length }` (number). | | `scan` | object | The scan requested for this item, if any (see below). *nullable.* | | `folder` | object | The folder it's filed in — `{ id, name, color }`. *nullable.* | The embedded `scan` object is a summary: `uuid` (fetch the full scan at `/v1/scans/{uuid}`), `status`, `category` (`SCAN_REQUEST` or `UNBOXING_REQUEST`), and `label` (nullable). Relationships: a mail item may belong to one **folder** and be the subject of a **scan** and a **shipment**. ## Scan A request to scan (or open-and-scan) a mail item. | Field | Type | Notes | | ------------------- | ------- | ----------------------------------------------------------------------------------------------------- | | `id` | string | Scan id (UUID). | | `mail_id` | string | Id of the scanned mail item (numeric string). | | `type` | string | `SCAN_REQUEST` (scan the item) or `UNBOXING_REQUEST` (open it and scan contents). | | `status` | string | `IN_PROCESS`, `COMPLETED`, `CANCELLED`, `REJECTED`, `DELETED`, or `RESTORING`. | | `is_expedited` | boolean | | | `instruction` | string | *nullable.* | | `reject_reason` | string | Why the request was rejected. Null unless `status` is `REJECTED`. *nullable.* | | `label` | string | Short AI-generated document label (e.g. "Insurance"). Requires a plan with scan labeling. *nullable.* | | `status_updated_at` | string | When the current `status` was reached — for completed scans, the completion time. *nullable.* | | `auto_delete_on` | string | When the scan file is permanently deleted — download it before this date. *nullable.* | | `created_at` | string | *ISO-8601.* | | `updated_at` | string | Last change of any kind — use `status_updated_at` for status timing. *ISO-8601.* | **Scan file** (from the download endpoint): `url` (string — short-lived signed URL; fetch promptly, don't store it) and `expires_at` (ISO-8601). **Scan summary** (AI-generated, when available): `label` (nullable) and `summary` (array of strings, one bullet per entry; nullable). ## Shipment A request to forward mail, return it to sender, deposit a check, or pick it up. Read-only. | Field | Type | Notes | | --------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | `id` | string | Shipment id (UUID). | | `type` | string | One of `shipment`, `return_to_sender`, `check_deposit`, `pickup`. | | `status` | string | Customer-facing group: `shipped`, `in_progress`, `payment_failed`, `rejected`. | | `item_count` | integer | Number of mail items packed into the request. | | `mail_items` | array | The packed items — each `{ id, mail_type, sender_name, arrival_date, envelope_image_url }`. | | `destination` | object | Where it ships to (`shipment` & `check_deposit` only) — an address value. *nullable.* | | `tracking_number` | string | Carrier tracking number, once on its way. *nullable.* | | `service_name` | string | Carrier service (e.g. "FedEx International Priority"). *nullable.* | | `requested_ship_date` | string | The ship-out date the customer asked for. *nullable.* | | `created_on` | string | When the request was made. *ISO-8601.* | | `is_expedited` | boolean | | | `is_insured` | boolean | | | `insured_amount` | number | Insured value in USD. Null when not insured. *nullable.* | | `declared_value` | number | Total declared customs value of the packed items, in USD. | | `deposit_check_slip_company_name` | string | `check_deposit` only. *nullable.* | | `instructions` | string | Packing instructions given when the request was made. *nullable.* | | `reject_reason` | string | Why rejected. Null unless `status` is `rejected`. *nullable.* | ## Folder A user-defined label for organizing mail. Deleting a folder unfiles the mail inside it (the mail is not deleted). | Field | Type | Notes | | ------------ | ------ | --------------------------------------------------------------- | | `id` | string | Folder id (numeric string) — mail references it as `folder_id`. | | `name` | string | | | `color` | string | Hex color like `#4BB94B`. *nullable.* | | `created_on` | string | *ISO-8601.* | | `updated_on` | string | *ISO-8601.* | ## Address A shipping or deposit destination. One address per type can be the default. | Field | Type | Notes | | -------------- | ------- | --------------------------------------------------------------------------------- | | `id` | string | Address id (UUID). | | `type` | string | `shipping` (a shipment destination) or `deposit` (where check deposits are sent). | | `is_default` | boolean | The default address of its `type` — one per type. | | `name` | string | Recipient name on the address. *nullable.* | | `line1` | string | *nullable.* | | `line2` | string | *nullable.* | | `line3` | string | *nullable.* | | `city` | string | *nullable.* | | `state` | string | *nullable.* | | `postal_code` | string | *nullable.* | | `country` | string | *nullable.* | | `phone_number` | string | *nullable.* | | `tax_id` | string | *nullable.* | ## Bank account A bank account used for check deposits. The account number is write-only and never returned in full. | Field | Type | Notes | | ---------------------- | ------ | ---------------------------------------- | | `id` | string | Bank account id (UUID). | | `bank_name` | string | | | `bank_state` | string | | | `account_number_last4` | string | Last 4 characters of the account number. | ## Account The customer account behind the API key. | Field | Type | Notes | | -------------- | ------ | ------------------------------------------------------------------------------- | | `id` | string | Account id (UUID). | | `name` | string | | | `email` | string | | | `phone_number` | string | *nullable.* | | `status` | string | Account status as reported by USGM (e.g. `APPROVED`, `SUSPENDED`). *nullable.* | | `box_number` | string | The PMB (private mailbox) number. Null until a mailbox is assigned. *nullable.* | | `created_at` | string | Registration date. *ISO-8601.* | ## Mailing address Your virtual US mailing address — the address to hand out so mail is routed to your mailbox. | Field | Type | Notes | | ------------- | ------ | -------------------------------------------------------------------------- | | `box_number` | string | The PMB (private mailbox) number — include it on every inbound mail piece. | | `formatted` | string | The complete address on one line, ready to hand out. | | `line1` | string | *nullable.* | | `line2` | string | *nullable.* | | `line3` | string | *nullable.* | | `city` | string | *nullable.* | | `state` | string | *nullable.* | | `postal_code` | string | *nullable.* | | `country` | string | *nullable.* |