Core concepts

Resource models

The objects the API returns, and how they relate.

The API is organized around a handful of resources. This page is the map; the API Reference has the exhaustive, always-current field list and types for each one.

Mail items

A physical piece of mail received at your address — the core resource.

Folders

Labels you organize mail into.

Addresses

Your shipping and deposit destinations.

Shipments

Requests to forward mail to one of your addresses.

Mail item

A scanned piece of mail. The central object you list, read, organize, archive, and discard.

FieldTypeNotes
idstring (numeric)Stable identifier, e.g. "80421".
senderstringWho the mail is from, when known.
typestringMail type (letter, package, …).
is_readbooleanWhether you’ve marked it read.
folder_idstring | nullThe folder it’s filed in, if any.
received_atstring (ISO-8601)When it arrived at the facility.

Relationships: a mail item may belong to one folder and can be the subject of a shipment.

Folder

A user-defined label for organizing mail. Deleting a folder unfiles the mail inside it (the mail is not deleted).

FieldTypeNotes
idstring (numeric)Stable identifier.
namestringDisplay name.
colorstringLabel color.

Address

A shipping or deposit destination. One address per category can be the default.

FieldTypeNotes
idstring (UUID)Stable identifier.
categorystringshipping or deposit.
is_defaultbooleanWhether it’s the default for its category.
line1, city, state, postal_code, countrystringThe postal address.

Shipment

A read-only record of a request to forward mail to one of your addresses.

FieldTypeNotes
idstring (UUID)Stable identifier.
category_typestringWhat kind of shipment this is.
statusstringCurrent state of the request.

Ids are strings. Mail items and folders use numeric strings ("80421"); addresses and shipments use UUIDs. Timestamps are ISO-8601 strings, so the SDKs map them to native date types.