US Global Mail API Documentation

{
  "id": "123456789",
  "is_read": true,
  "mail_status": "Received",
  "mail_type": "LETTER",
  "mail_type_label": "Large Letter",
  "measurement": {
    "width": 9.5,
    "height": 4,
    "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": "blue"
  }
}

Mark the item read/unread and/or move it into a folder

Authentication

AuthorizationBearer

Your API key, sent as Authorization: Bearer usgmk_live_… in production or usgmk_test_… in the sandbox.

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 nullOptional

recipient_namestring or nullOptional

arrival_datedatetime or nullOptional

When the item arrived at the facility.

envelope_image_urlstring or nullOptional

Photo of the item/envelope.

quarantine_reasonstring or nullOptional

scanobject or nullOptional

The scan requested for this item, when one exists.

tracking_numberstring or nullOptional

Inbound carrier tracking number, when one was captured.

sender_addressstring or nullOptional

folderobject or nullOptional

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 '{}'