{
  "openapi": "3.1.0",
  "info": {
    "title": "MailPulse API",
    "description": "Send a REAL physical letter — US First-Class, US Certified Mail (with optional electronic return receipt), or international — via Lob's Print & Mail network. This is an ACTION API, not a data lookup: paying causes a real letter to be printed and mailed. Flow: free quote -> paid send -> optional status poll. Pay-per-call via x402 (USDC on Base). No API keys, no accounts, no subscriptions.",
    "version": "1.0.0",
    "contact": {
      "name": "The Aslan Group LLC",
      "url": "https://pulsenetwork.theaslangroupllc.com",
      "email": "info@theaslangroupllc.com"
    },
    "x-guidance": "# MailPulse API (x402 pay-per-call)\n\nSend a REAL physical letter — US First-Class, US Certified Mail (with optional electronic return receipt), or international — via Lob's Print & Mail network. ACTION API, not a data lookup: paying causes a real letter to be printed and mailed. Flow: free quote -> paid send -> optional status/tracking poll. Pay-per-call via x402 on Base.\n\nBase URL: https://mailpulse.theaslangroupllc.com\n\n## Payment\nAll paid endpoints use the x402 protocol (HTTP 402): USDC on Base mainnet (eip155:8453). No API keys, no accounts, no subscriptions — pay per call.\n\n## Agent workflow\n1. Request the endpoint. Unpaid requests receive a 402 challenge with exact price and pay-to details (the challenge is returned before request validation).\n2. Settle with any x402 client (agentcash fetch, x402-fetch, x402-axios) and retry with the X-PAYMENT header.\n3. Responses are JSON. Prices below are fixed per call.\n\n## Paid endpoints\n- POST /api/verify-address — $0.01 — Deliverability check (US + international) via Lob address verification, before you pay to print.\n- POST /api/letters — $3 — THE action: prints and mails a real physical letter once payment settles. Requires a verified quote_id and a client_request_id for idempotency. Price varies $3.\n- GET /api/letters/{id} — $0.005 — Cheap status/USPS tracking poll for a previously sent letter.\n\nMore APIs from this provider: https://pulsenetwork.theaslangroupllc.com (grouped catalog, all x402)."
  },
  "servers": [
    {
      "url": "https://mailpulse.theaslangroupllc.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Liveness + current mode",
        "description": "Free liveness check. Reports whether the service is currently in test or live Lob mode.",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service is up"
          }
        }
      }
    },
    "/api/verify-address": {
      "post": {
        "summary": "Verify a mailing address (US + international)",
        "description": "Deliverability check before you pay to print. Wraps Lob's US Address Verification (USPS CASS-based) and international address verification. Returns a deliverability verdict and a standardized address. Run this before /api/quote and /api/letters to reduce the risk of paying to mail an undeliverable address.",
        "operationId": "verifyAddress",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "address": {
                    "type": "object",
                    "required": [
                      "address_line1"
                    ],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "company": {
                        "type": "string"
                      },
                      "address_line1": {
                        "type": "string"
                      },
                      "address_line2": {
                        "type": "string"
                      },
                      "address_city": {
                        "type": "string"
                      },
                      "address_state": {
                        "type": "string"
                      },
                      "address_zip": {
                        "type": "string"
                      },
                      "address_country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2, default US"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deliverability verdict + standardized address"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.01,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run before POST /api/quote and POST /api/letters to avoid paying to mail an undeliverable address.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/quote": {
      "post": {
        "summary": "Free price quote for a letter",
        "description": "FREE — no x402 gate, no Lob call. Returns the exact fixed price for the requested service, a signed quote_id (HMAC, tamper-evident), and a 15-minute expiry. Copy the response's `order`, `quote_id`, `issued_at` and `amount_micro` verbatim into POST /api/letters.",
        "operationId": "quoteLetter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "service",
                  "to",
                  "from",
                  "content"
                ],
                "properties": {
                  "service": {
                    "type": "string",
                    "enum": [
                      "standard",
                      "certified",
                      "certified_return_receipt",
                      "international"
                    ]
                  },
                  "to": {
                    "type": "object",
                    "description": "Recipient address"
                  },
                  "from": {
                    "type": "object",
                    "description": "Sender-of-record address"
                  },
                  "content": {
                    "type": "object",
                    "description": "{ html: string } or { file_url: string } — exactly one"
                  },
                  "pages_estimate": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6,
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed quote: quote_id, issued_at, expires_at, price_usd, amount_micro, order"
          }
        }
      }
    },
    "/api/letters": {
      "post": {
        "summary": "Send a physical letter (THE paid action)",
        "description": "Prints and mails a real physical letter via Lob once payment settles. Requires a quote_id from POST /api/quote (recomputed and verified server-side; mismatched or expired quotes are rejected with 400 BEFORE payment is requested) and a client_request_id (8-128 chars) for idempotency — replaying the same client_request_id with the same order returns the original result without double-charging or double-sending. Price varies by service: standard $3.00, certified $12.00, certified_return_receipt $14.00, international $5.00 (see /pricing.md). Every order is capped at $25.00 total.",
        "operationId": "sendLetter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "quote_id",
                  "issued_at",
                  "amount_micro",
                  "service",
                  "to",
                  "from",
                  "content",
                  "client_request_id"
                ],
                "properties": {
                  "quote_id": {
                    "type": "string",
                    "description": "From POST /api/quote"
                  },
                  "issued_at": {
                    "type": "string",
                    "description": "From POST /api/quote, copied verbatim"
                  },
                  "amount_micro": {
                    "type": "string",
                    "description": "From POST /api/quote, copied verbatim"
                  },
                  "service": {
                    "type": "string",
                    "enum": [
                      "standard",
                      "certified",
                      "certified_return_receipt",
                      "international"
                    ]
                  },
                  "pages_estimate": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 6,
                    "default": 1
                  },
                  "to": {
                    "type": "object",
                    "description": "Recipient address — identical to the quote"
                  },
                  "from": {
                    "type": "object",
                    "description": "Sender-of-record address — identical to the quote"
                  },
                  "content": {
                    "type": "object",
                    "description": "Identical to the quote"
                  },
                  "client_request_id": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 128,
                    "description": "Unique per letter. Enables safe retries — replay returns the original result, never a duplicate send."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lob letter id, status, expected_delivery_date, carrier, tracking_number, price_charged_usd, mode"
          },
          "400": {
            "description": "Invalid, expired, tampered, or over-cap order — rejected before payment"
          },
          "402": {
            "description": "Payment required"
          },
          "409": {
            "description": "client_request_id reused for a different order"
          }
        },
        "x-price-usd": 3,
        "x-price-usd-note": "Price varies by service: standard $3.00, certified $12.00, certified_return_receipt $14.00, international $5.00. The actual x402 402 challenge amount always matches the caller's quote_id-verified order; $3.00 shown here is the representative/minimum price for discovery purposes.",
        "x-agent-use-case": "action",
        "x-agent-chaining": "Always call POST /api/quote first (free); optionally POST /api/verify-address before quoting. Poll GET /api/letters/{id} afterward for status/tracking.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "3.000000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/letters/{id}": {
      "get": {
        "summary": "Letter status / USPS tracking poll",
        "description": "Cheap status/tracking poll for a previously sent letter. Returns render status, expected delivery date, and (for certified mail) the USPS tracking number.",
        "operationId": "getLetterStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ltr_[a-zA-Z0-9]+$"
            },
            "description": "Lob letter id returned by POST /api/letters"
          }
        ],
        "responses": {
          "200": {
            "description": "id, status, expected_delivery_date, carrier, tracking_number, pdf_url"
          },
          "402": {
            "description": "Payment required"
          },
          "404": {
            "description": "No letter with that id in the current mode (test/live are separate namespaces)"
          }
        },
        "x-price-usd": 0.005,
        "x-agent-use-case": "on-demand",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.005000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    }
  }
}