Sandbox

Some things that happen to your mailbox are done by USGM operators in the warehouse, on physical mail — not by you through the API. Two in particular:

• Mail arriving. New mail items appear when an operator receives and logs a physical piece.
• A scan being performed. When you request a scan, an operator physically scans the item; only then does the scan reach COMPLETED with a downloadable file.

In production there’s no API to make those happen — they’re real-world actions. But while you’re building against the sandbox, there’s no warehouse and no physical mail, so you’d have nothing to list, scan, or ship. The sandbox module fills that gap: a small set of endpoints that let you simulate the operator’s side so you can exercise your whole integration without waiting on real mail.

Seed mailbox

POST /v1/sandbox/seed — populate your sandbox mailbox with a ready-made set of sample mail items in one call. Takes no body; returns the ids of everything it created.

$
curl -X POST https://api-sandbox.usglobalmail.com/v1/sandbox/seed \
>
  -H "Authorization: Bearer $USGM_TEST_KEY"

1
{ "mail_ids": ["100001", "100002", "100003"] }

Use it once at the start of a test run to get a populated inbox to list, filter, organize, and scan.

Seed mail

POST /v1/sandbox/seed/mail — add a single mail item, shaped to the case you’re testing. Every field is optional; omit the body entirely to get a sample letter.

The mail_type matters: LETTER and LARGELETTER accept a flat SCAN_REQUEST, while the bulkier types accept an UNBOXING_REQUEST (open-and-scan) — so seed the type that matches the scan flow you want to test.

$
curl -X POST https://api-sandbox.usglobalmail.com/v1/sandbox/seed/mail \
>
  -H "Authorization: Bearer $USGM_TEST_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "sender_name": "Internal Revenue Service",
>
    "mail_type": "PACKAGE",
>
    "weight": 2.5,
>
    "measurement": { "width": 8, "height": 4, "length": 10 }
>
  }'

1
{ "mail_id": "100004" }

Complete scan

POST /v1/sandbox/scans/{id}/complete — force one of your pending scan requests to COMPLETED, standing in for the operator who would physically scan the item. Pass the scan’s id in the path.

The sandbox has no scanning AI, so the body (optional) lets you supply the label and summary the AI would normally generate — handy for exercising the scan’s label field and the GET /v1/scans/{id}/summary endpoint.

$
curl -X POST https://api-sandbox.usglobalmail.com/v1/sandbox/scans/SCAN_ID/complete \
>
  -H "Authorization: Bearer $USGM_TEST_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "label": "Insurance",
>
    "summary": ["Auto policy renewal", "Amount due: $482.00", "Due date: 2026-08-01"]
>
  }'

The response is the completed scan, now with a downloadable file.

Putting it together

A typical end-to-end test drives your integration through the full scan lifecycle — you play both sides: