3LT Letter Mail

Create a letter DRAFT: verifies the recipient address with PostGrid, screens content, and returns a price quote. This NEVER mails anything. Pass EITHER html (letter body as an HTML string) OR pdf_path (path to a PDF file on the server). PDF text is extracted for screening; if extraction fails the draft is kept but flagged needs_review.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "your 3L-Group Technology API key (lms_...)."
    },
    "to": {
      "additionalProperties": true,
      "type": "object",
      "description": "recipient address dict with name, address_line1, address_city,\naddress_state, address_zip (US)."
    },
    "from_address": {
      "additionalProperties": true,
      "type": "object",
      "description": "sender address dict, same shape as `to`."
    },
    "html": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "letter body as an HTML string (use this OR pdf_path)."
    },
    "pdf_path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "server-local path to a PDF to mail instead of html."
    },
    "color": {
      "default": false,
      "type": "boolean",
      "description": "True for color printing, False for black & white."
    },
    "quantity": {
      "default": 1,
      "type": "integer",
      "description": "number of identical letters (10+ gets the bulk rate)."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "optional label for your own records."
    },
    "certified": {
      "default": false,
      "type": "boolean",
      "description": "OPT-IN ONLY — True for USPS Certified Mail with Electronic\nReceipt (tracked, signature on delivery). Defaults to False, which\nsends standard First Class mail. Only set True when the customer\nexplicitly asked for certified mail: it costs significantly more\n(PostGrid's certified rate + the flat $1.00 service fee, roughly\n$11 per letter). Never default this to True."
    }
  },
  "required": [
    "api_key",
    "to",
    "from_address"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Request that a draft be mailed. approval-tier keys: creates a PENDING request and returns a one-tap Allow/Deny approval_url for the human. Nothing is mailed until Allow. on_command keys: may auto-send inside guardrails (spend caps, content screening, anomaly detection); anything outside them stays PENDING.

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "your 3L-Group Technology API key (lms_...)."
    },
    "draft_id": {
      "type": "integer",
      "description": "the draft_id returned by draft_letter."
    }
  },
  "required": [
    "api_key",
    "draft_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}

Check a send request: status (PENDING/SENT/REJECTED/FAILED), the key's trust tier and tier decision, approval state (+approval_url while pending), and billing state (Stripe charge id when billed).

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "your 3L-Group Technology API key (lms_...)."
    },
    "request_id": {
      "type": "integer",
      "description": "the request_id returned by request_send."
    }
  },
  "required": [
    "api_key",
    "request_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "additionalProperties": true
}