mail.easy API Documentation

Authorization Headers

Header Source

cjbapi-client cjbapi-client value from /autho response

cjbapi-key cjbapi-key value from /autho response

Header	Source
cjbapi-client	`cjbapi-client` value from /autho response
cjbapi-key	`cjbapi-key` value from /autho response

Response Status Codes

200 Success
400 Schema / data validation failure
500 Bad API call / server error

Authentication

POST /maileasy/autho Client login — receive API key ▼

Request Body

{
  "clientkey": "your-client-key",
  "secret":    "your-secret"
}

Field	Type		Description
clientkey	string	required	Your mail.easy client key
secret	string	required	Your client secret

Response Body

{
  "cjbapi-client": "...",
  "cjbapi-key":    "...",
  "expire_at":     "2026-06-21 20:49:34",
  "status":        "success"
}

ℹ️ API keys have a 24-hour life. Store cjbapi-client and cjbapi-key from the response and pass them as headers on all subsequent requests.

Preflight

POST /maileasy/preflight/submit Add preflight dataset ▼

Request Body — array of mail items

[
  {
    "uniqueID":                  "1001",
    "mail_class":                "FC",
    "package_type":              "LETTER",
    "weight":                    1.0,
    "unit":                      "OZ",
    "sheets_of_paper":           3,
    "zip11":                     "94010150950",
    "tracking_servicetype_code": ""
  }
]

Field	Type		Description
uniqueID	string	required	Unique identifier for this mail item
mail_class	FC \| MM	required	FC = First Class, MM = Marketing Mail
package_type	LETTER \| FLAT \| POSTCARD	required	Physical mail piece type
weight	number ≥ 0	required	Weight of the mail piece. 1.0 = 1 oz, 3.5 = 3½ oz
unit	OZ	required	Unit of weight measurement
sheets_of_paper	integer ≥ 0	required	Number of sheets of paper enclosed
zip11	string	required	11-digit ZIP+4 delivery point barcode. Empty string if unavailable
tracking_servicetype_code	string	required	USPS tracking STC code. Empty string if no tracking

Response Body

{
  "preflight_id":            "4306946e-6fc2-4787-8be9-2d5d861f8177",
  "postage_statement_id":    "ffa5f855-246f-445f-b9c5-abd5e359eb7b",
  "Incoming data validation":"Request payload is valid",
  "preflight_pieces":        1,
  "invalid_pieces":          0,
  "data": [
    {
      "uniqueID":              "1001",
      "mail_class":            "FC",
      "package_type":          "LETTER",
      "weight":                1.0,
      "unit":                  "OZ",
      "sheets_of_paper":       3,
      "zip11":                 "94010150950",
      "tracking_servicetype_code": "",
      "rate_category":         "MIXEDAADC",
      "processing_category":   "LT",
      "is_certified":          false,
      "is_electrr":            false,
      "stc_description":       "",
      "trayid":                "027593",
      "pfpid":                 1,
      "sortation_notes":       "Sorted to MIXEDAADC Successfully",
      "aadc":                  "940",
      "success":               true,
      "notes":                 "",
      "tray_content":          "MIXEDAADC",
      "ibm_code":              "",
      "trackingid_code":       "",
      "usps_ref_number":       "",
      "imb_code":              "0014190146421304175894010150950",
      "usps_ref_code":         "41758"
    }
  ],
  "total_trays": 1,
  "trays": [
    {
      "tray_id":            "027593",
      "build":              "UPDATED-TRAY",
      "content":            "MIXEDAADC",
      "mail_class":         "FC",
      "processing_category":"LT",
      "rate_category":      "MIXEDAADC",
      "is_certified":       false,
      "expected_count":     1
    }
  ]
}

JSON Schema — draft 2020-12

{
  "$id":     "json_schema_preflight.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title":   "Mail Item Dataset",
  "description": "Array of mail items submitted for processing",
  "type":    "array",
  "items": {
    "type": "object",
    "required": [
      "uniqueID","mail_class","package_type",
      "weight","unit","sheets_of_paper",
      "zip11","tracking_servicetype_code"
    ],
    "properties": {
      "uniqueID":                  { "type": "string" },
      "mail_class":                { "type": "string",  "enum": ["FC","MM"] },
      "package_type":              { "type": "string",  "enum": ["LETTER","FLAT","POSTCARD"] },
      "weight":                    { "type": "number",  "minimum": 0 },
      "unit":                      { "type": "string",  "enum": ["OZ"] },
      "sheets_of_paper":           { "type": "integer", "minimum": 0 },
      "zip11":                     { "type": "string" },
      "tracking_servicetype_code": { "type": "string" }
    }
  }
}

ℹ️ If there is no currently active postage statement, one will be created automatically.

GET /maileasy/preflight/{preflight_id}/dataset Retrieve preflight dataset ▼

Response Body — same structure as preflight/submit response

{
  "preflight_id":         "4306946e-6fc2-4787-8be9-2d5d861f8177",
  "postage_statement_id": "ffa5f855-246f-445f-b9c5-abd5e359eb7b",
  "preflight_pieces":     1,
  "invalid_pieces":       0,
  "data":  [ { "...": "see preflight/submit response" } ],
  "total_trays": 1,
  "trays": [ { "...": "see preflight/submit response" } ]
}

GET /maileasy/preflight/active List active preflights ▼

{
  "data": [
    {
      "date":             "2026-05-22",
      "id":               "bf77ce00-17fd-4865-898c-8045e020de5f",
      "postage_statement":"ffa5f855-246f-445f-b9c5-abd5e359eb7b",
      "status":           "ACTIVE",
      "total_pieces":     "3546"
    },
    {
      "date":             "2026-05-22",
      "id":               "4306946e-6fc2-4787-8be9-2d5d861f8177",
      "postage_statement":"ffa5f855-246f-445f-b9c5-abd5e359eb7b",
      "status":           "ACTIVE",
      "total_pieces":     "2"
    }
  ],
  "status": "success"
}

DELETE /maileasy/preflight/{preflight_id}/delete Delete active preflight ▼

{
  "message": "Preflight 4306946e-6fc2-4787-8be9-2d5d861f8177 deleted for clientkey ad509b2f-816c-4860-a123-514c3bc6f09b",
  "status":  "success"
}

GET /maileasy/preflight/schema Retrieve preflight JSON schema ▼

{
  "$id":     "json_schema_preflight.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title":   "Mail Item Dataset",
  "description": "Array of mail items submitted for processing",
  "type":    "array",
  "items": {
    "type": "object",
    "required": ["uniqueID","mail_class","package_type","weight","unit","sheets_of_paper","zip11","tracking_servicetype_code"],
    "properties": {
      "uniqueID":                  { "type": "string",  "description": "Unique identifier for this mail item" },
      "mail_class":                { "type": "string",  "enum": ["FC","MM"], "description": "Mail class: FC=First Class, MM=Marketing Mail" },
      "package_type":              { "type": "string",  "enum": ["LETTER","FLAT","POSTCARD"], "description": "Physical mail piece type" },
      "weight":                    { "type": "number",  "minimum": 0, "description": "Weight of the mail piece" },
      "unit":                      { "type": "string",  "enum": ["OZ"], "description": "Unit of weight measurement" },
      "sheets_of_paper":           { "type": "integer", "minimum": 0, "description": "Number of sheets enclosed" },
      "zip11":                     { "type": "string",  "description": "11-digit ZIP+4 delivery point barcode" },
      "tracking_servicetype_code": { "type": "string",  "description": "USPS tracking STC code, empty string if none" }
    }
  }
}

GET /maileasy/preflight/stc_codes Retrieve USPS STC code list ▼

Response sample coming soon Returns the current list of valid USPS Service Type Codes (STC) for use in the tracking_servicetype_code field.

Postage Statements

GET /maileasy/ps/fetch/active Retrieve active postage statement ▼

[
  {
    "postage_statement_id": "ffa5f855-246f-445f-b9c5-abd5e359eb7b",
    "date":                 "2026-05-22",
    "status":               "ACTIVE",
    "pieces":               "3548",
    "preflight_count":      2,
    "preflight_list": [
      {
        "id":           "bf77ce00-17fd-4865-898c-8045e020de5f",
        "date":         "2026-05-22",
        "total_pieces": "3546",
        "status":       "ACTIVE"
      },
      {
        "id":           "4306946e-6fc2-4787-8be9-2d5d861f8177",
        "date":         "2026-05-22",
        "total_pieces": "2",
        "status":       "DELETED"
      }
    ]
  }
]

ℹ️ Only one postage statement can be active (current) at a time.

GET /maileasy/ps/fetch/completed List completed postage statements ▼

Response Body — same structure as /ps/fetch/active

[
  {
    "postage_statement_id": "...",
    "date":                 "2026-05-22",
    "status":               "COMPLETED",
    "pieces":               "...",
    "preflight_count":      0,
    "preflight_list":       []
  }
]

ℹ️ You can have multiple completed postage statements pending USPS submission.

GET /maileasy/ps/fetch/range:YYYY-MM-DD Retrieve statements by date range ▼

Response Body — same structure as /ps/fetch/active

[
  {
    "postage_statement_id": "...",
    "date":                 "...",
    "status":               "...",
    "pieces":               "...",
    "preflight_count":      0,
    "preflight_list":       []
  }
]

ℹ️

Range format controls date scope:
range:2026 — all of 2026
range:2026-05 — all of May 2026
range:2026-05-22 — a single day

GET /maileasy/ps/{postage_statement_id}/dataset Retrieve postage statement dataset ▼

{
  "postage_statement_id": "ffa5f855-246f-445f-b9c5-abd5e359eb7b",
  "date":                 "2026-05-22",
  "status":               "ACTIVE",
  "preflight_count":      1,
  "preflight_list": [
    {
      "id":           "bf77ce00-17fd-4865-898c-8045e020de5f",
      "date":         "2026-05-22",
      "total_pieces": "2"
    }
  ],
  "tray_count": 1,
  "tray_list": [
    {
      "trayid":               "027559",
      "content":              "40512",
      "mail_class":           "FC",
      "processing_category":  "LT",
      "count":                "2"
    }
  ],
  "piece_count": 2,
  "piece_list": [
    {
      "preflight_id": "bf77ce00-17fd-4865-898c-8045e020de5f",
      "uniqueid":     "1001",
      "trayid":       "027559",
      "mail_class":   "FC",
      "package_type": "LETTER"
    },
    {
      "preflight_id": "bf77ce00-17fd-4865-898c-8045e020de5f",
      "uniqueid":     "1002",
      "trayid":       "027559",
      "mail_class":   "FC",
      "package_type": "LETTER"
    }
  ]
}

POST /maileasy/ps/{postage_statement_id}/complete Complete postage statement ▼

Request Body — array of uniqueIDs to include

[
  { "uniqueID": "1001" },
  { "uniqueID": "1002" }
]

Field	Type		Description
uniqueID	string	required	ID of a mail piece to include in the USPS postage statement

{
  "postage_statement_id":    "ffa5f855-246f-445f-b9c5-abd5e359eb7b",
  "postage_statements_total": 1,
  "postage_statements": [
    {
      "mail_class":    "FC",
      "type":          "LETTER",
      "pieces":        1,
      "postage":       "0.67",
      "extra_services":"0.00"
    }
  ],
  "trays_total": 1,
  "trays": [
    {
      "trayID":              "027579",
      "content":             "913",
      "processing_category": "LT",
      "rate_category":       "AADC",
      "tray_type":           "EMM",
      "pieces":              "1",
      "containerID":         "900123234027579"
    }
  ],
  "included_piece_count": 1,
  "pieces": [
    {
      "uniqueID":      "1001",
      "trayid":        "027579",
      "postage":       "0.67",
      "extra_services":"0.00"
    }
  ],
  "preflight_count": 1,
  "preflights": [
    {
      "id":           "bf77ce00-17fd-4865-898c-8045e020de5f",
      "date":         "2026-05-22",
      "total_pieces": "3546"
    }
  ]
}

⚠️ Send the uniqueIDs of all mail pieces you want included across all associated preflights. Any pieces not listed will be excluded and will not appear in the USPS postage statement.

POST /maileasy/ps/{postage_statement_id}/submit Submit to USPS ▼

ℹ️ No request body required. The postage statement must be in COMPLETED status before submission.

Response sample coming soon Submits a completed postage statement to USPS for processing.

Client Settings

POST /client/secrets/add Add USPS credential ▼

Request Body

{
  "type":   "usps_ship",
  "key":    "username",
  "secret": "password",
  "notes":  "some notes about this credential"
}

Field	Type		Description
type	mail.dat \| usps_ship \| pdx \| epf \| IV	required	USPS credential type
key	string	required	Username or key
secret	string	required	Password or secret
notes	string	required	Notes about this credential

{
  "status": "credential updated successfully"
}

JSON Schema — draft 2020-12

{
  "$id":     "json_schema_client_secret.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title":   "USPS Credentials",
  "description": "USPS credentials for postage submission and tracking",
  "type":    "object",
  "required": ["type","key","secret","notes"],
  "properties": {
    "type":   { "type": "string", "enum": ["mail.dat","usps_ship","pdx","epf","IV"], "description": "USPS credential type" },
    "key":    { "type": "string", "description": "Username or Key" },
    "secret": { "type": "string", "description": "Password or Secret" },
    "notes":  { "type": "string", "description": "Notes about this credential" }
  }
}

GET /client/secrets/fetch List all USPS credentials ▼

[
  { "type": "mail.dat",  "key": "testingkey55", "secret": "testingsecret55", "notes": "testingnotes555" },
  { "type": "usps_ship", "key": "",             "secret": "",                "notes": "" },
  { "type": "pdx",       "key": "",             "secret": "",                "notes": "" },
  { "type": "epf",       "key": "",             "secret": "",                "notes": "" },
  { "type": "iv",        "key": "",             "secret": "",                "notes": "" }
]

DELETE /client/secrets/delete Clear all USPS credentials ▼

⚠️ This removes all USPS credentials from your account. No request body required. Returns HTTP 200 on success. This action cannot be undone.