Update | USGM Public API

{
  "id": "123456789",
  "is_read": false,
  "mail_status": "Delivered",
  "mail_type": "LETTER",
  "mail_type_label": "Large Letter",
  "measurement": {
    "width": 8.5,
    "height": 11,
    "length": 0.2
  },
  "weight": 0.5,
  "has_storage_charges": false,
  "sender_name": "John Doe",
  "recipient_name": "Jane Smith",
  "arrival_date": "2024-01-15T09:30:00Z",
  "envelope_image_url": "https://usglobalmail.com/images/envelopes/123456789.jpg",
  "quarantine_reason": "None",
  "scan": {
    "uuid": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
    "status": "COMPLETED",
    "category": "SCAN_REQUEST",
    "label": "Invoice"
  },
  "tracking_number": "9400110200881234567890",
  "sender_address": "123 Main St, Springfield, IL 62704, USA",
  "folder": {
    "id": "42",
    "name": "Important",
    "color": "#FF5733"
  }
}

Authentication

AuthorizationBearer

Your API key, sent as Authorization: Bearer usgmk_live_....

Path parameters

idstringRequired

Request

This endpoint expects an object.

is_readbooleanOptional

folder_idstring or nullOptionalformat: "^\d+$"

Move the item to this folder. Pass null to remove it from its folder.

Response

idstring

Mail item id (numeric string).

is_readboolean

mail_statusstring

Lifecycle status as reported by the mailroom.

mail_typestring

mail_type_labelstring

Human-readable form of mail_type (e.g. “Large Letter”).

measurementobject

Item dimensions, in inches.

weightdouble

Item weight, in pounds.

has_storage_chargesboolean

Whether the item is currently accruing storage charges.

sender_namestring or null

recipient_namestring or null

arrival_datedatetime or null

When the item arrived at the facility.

envelope_image_urlstring or null

Photo of the item/envelope.

quarantine_reasonstring or null

scanobject or null

The scan requested for this item, when one exists.

tracking_numberstring or null

Inbound carrier tracking number, when one was captured.

sender_addressstring or null

folderobject or null

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

$	curl -X PATCH https://api.usglobalmail.com/v1/mails/id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'