v1.0

321Certified REST API

Send certified mail programmatically. Simple, RESTful, and designed for developers.

Authentication

All API requests require authentication using an API key. Include your key in theAuthorization header:

Authorization: Bearer 321m_live_xxxxxxxxxxxx

Or use the X-API-Key header:

X-API-Key: 321m_live_xxxxxxxxxxxx

Security: Keep your API key secret. Never expose it in client-side code or public repositories.

Base URL

https://api.321certified.com/api/v1

Error Handling

Errors return a consistent JSON structure:

{
  "error": {
    "message": "Invalid API key",
    "code": "unauthorized",
    "status": 401
  }
}

Status	Code	Description
400	bad_request	Invalid request parameters
401	unauthorized	Missing or invalid API key
403	forbidden	Insufficient permissions
404	not_found	Resource not found
422	unprocessable_entity	Validation error (e.g., invalid address)
500	internal_error	Server error

Authentication

POST/api/v1/api-keysSession

Create a new API key

GET/api/v1/api-keysSession

List your API keys

DELETE/api/v1/api-keys/:idSession

Revoke an API key

Mailings

POST/api/v1/mailingsAPI Key

Create a new certified mailing

GET/api/v1/mailingsAPI Key

List your mailings

GET/api/v1/mailings/:idAPI Key

Get mailing details

GET/api/v1/mailings/:id/labelAPI Key

Download label PDF

Tracking

GET/api/v1/tracking/:trackingNumberAPI Key

Get tracking status and events

Addresses

POST/api/v1/addresses/validateAPI Key

Validate an address with USPS

Pricing

GET/api/v1/pricingAPI Key

Get pricing table

POST/api/v1/pricing/calculateAPI Key

Calculate price for a mailing

Examples

Create a Certified Mailing

curl -X POST https://api.321certified.com/api/v1/mailings \
  -H "Authorization: Bearer 321m_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "name": "John Smith",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105"
    },
    "to": {
      "name": "Jane Doe",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001"
    },
    "mail_class": "certified_return_receipt",
    "reference": "CASE-2024-001"
  }'

Response

{
  "id": "clx123abc",
  "tracking_number": "9400111899223456789012",
  "status": "label_generated",
  "mail_class": "certified_return_receipt",
  "cost": {
    "postage": 8.12,
    "service_fee": 1.64,
    "total": 9.76
  },
  "label_url": "/api/v1/mailings/clx123abc/label",
  "from": { ... },
  "to": { ... },
  "created_at": "2024-01-15T10:30:00Z"
}

Validate an Address

curl -X POST https://api.321certified.com/api/v1/addresses/validate \
  -H "Authorization: Bearer 321m_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "street1": "1600 Pennsylvania Ave",
    "city": "Washington",
    "state": "DC",
    "zip": "20500"
  }'

Get Tracking Status

curl https://api.321certified.com/api/v1/tracking/9400111899223456789012 \
  -H "Authorization: Bearer 321m_live_xxxx"

List Mailings with Filters

curl "https://api.321certified.com/api/v1/mailings?status=delivered&limit=10" \
  -H "Authorization: Bearer 321m_live_xxxx"

Permissions

API keys can be scoped with specific permissions:

Permission	Description
*	Full access (default)
mailings:read	Read mailings and tracking
mailings:write	Create new mailings
addresses:read	Validate addresses
pricing:read	View pricing information

Rate Limits

API requests are limited to ensure fair usage:

1,000 requests per minute per API key
10,000 requests per hour per account
Bulk operations count as multiple requests

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1642521600