---
title: "Get mail status"
method: GET
path: "/v1/mail/{mail_id}"
tags: ["mail"]
---

# Get mail status

`GET /v1/mail/{mail_id}`

## Request

- Base URL: `https://api.noerrands.com/c/mail`
- URL: `https://api.noerrands.com/c/mail/v1/mail/{mail_id}`
- Auth: HTTP bearer

Look up one mailpiece by mail_id with its delivery status and event history, refreshed from the print provider. Free. If the provider dropped the piece before printing, this call refunds its full charge to the balance, once.

## Path parameters

- `mail_id` string, required

## Response `200`

Success.

- object
  - `mail_id` string, required: Opaque id, "ml_...". Use it with get_mail_status.
  - `kind` 'letter' | 'postcard', required
  - `status` 'created' | 'processing' | 'in_transit' | 'delivered' | 'returned' | 'failed' | 'cancelled', required
  - `to` object, required: A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.
    - `name` string: Recipient or sender name, 1-40 characters.
    - `company` string: Optional company line, up to 40 characters.
    - `line1` string: Street address, up to 64 characters.
    - `line2` string: Apartment, suite, or unit, up to 64 characters.
    - `city` string, required
    - `state` string, required: Two-letter US state code.
    - `zip` string: ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted.
    - `country` 'US': US only in v0.
  - `from` object, required: A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.
    - `name` string: Recipient or sender name, 1-40 characters.
    - `company` string: Optional company line, up to 40 characters.
    - `line1` string: Street address, up to 64 characters.
    - `line2` string: Apartment, suite, or unit, up to 64 characters.
    - `city` string, required
    - `state` string, required: Two-letter US state code.
    - `zip` string: ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted.
    - `country` 'US': US only in v0.
  - `created_at` string, date-time, required
  - `expected_delivery_date` string, date: YYYY-MM-DD.
  - `credits_charged_cents` integer, required
  - `tracking_url` string, uri
  - `events` object[], required
    - `at` string, date-time, required
    - `status` 'created' | 'processing' | 'in_transit' | 'delivered' | 'returned' | 'failed' | 'cancelled', required
    - `detail` string

## Other responses

- `400`: invalid_request
- `401`: unauthorized. Carries WWW-Authenticate: Bearer resource_metadata="..."
- `403`: forbidden_scope: a write tool called with a read-only key.
- `404`: not_found
- `429`: rate_limited
- `502`: provider_error

---

[API](https://skmtc.dev/noerrands/apis/no-errands-mail-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-mail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-mail-api/revisions/391e96e083f5?raw)