US Global Mail API Documentation

The API is organized around a handful of resources. This page is the reference for each resource’s shape; the API Reference has the same fields as an interactive, always-live schema (and the request bodies for create/update endpoints).

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.