{ "openapi": "3.1.0", "info": { "title": "PostalAgent AI Mailroom Connector", "version": "1.0.0", "summary": "Virtual Mailbox Operated by AI", "description": "Have Muse manage a real virtual mailbox for your business or yourself. It digitizes incoming envelopes, provides 300 DPI duplex interior scanning, classifies and sets reminders for important notices including tax and legal notices. It can also physically and digitally forward scanned mail to specific people, automate USPS form completion, and coordinate online notarization.", "termsOfService": "https://postalagent.ai/terms", "contact": { "name": "Adam Matar (Skidnir & PostalAgent Support)", "email": "support@postalagent.ai", "url": "https://postalagent.ai" }, "license": { "name": "Proprietary", "url": "https://postalagent.ai/terms" } }, "servers": [ { "url": "https://api.postalagent.ai", "description": "Production API Gateway" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Enter your PostalAgent API Key or Tenant Token (e.g. postal_tenant_... or token_...)" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Postal-Key", "description": "PostalAgent API Key header" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error description" }, "code": { "type": "string", "description": "Internal error classification code" } }, "required": [ "error" ] }, "MailItem": { "type": "object", "properties": { "id": { "type": "string", "example": "postal_9401" }, "tenant_id": { "type": "string", "example": "tenant_apex" }, "sender_name": { "type": "string", "example": "Internal Revenue Service" }, "recipient_name": { "type": "string", "example": "Acme Ventures LLC" }, "recipient_address": { "type": "string", "example": "1209 Orange St, Wilmington, DE 19801" }, "envelope_scan_front": { "type": "string", "format": "uri" }, "envelope_scan_back": { "type": "string", "format": "uri" }, "interior_pages": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ocr_extracted_text": { "type": "string" }, "status": { "type": "string", "enum": [ "INGESTED", "SCANNED", "FORWARDED", "SETTLED", "SHRED_PENDING", "SHREDDED" ] }, "triage": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "LEGAL_NOTICE_OR_SUMMONS", "TAX_OR_IRS", "BANK_OR_CHECK", "CORPORATE_COMPLIANCE", "MARKETING_OR_JUNK" ] }, "priority": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "summary": { "type": "string" }, "action_required": { "type": "string" }, "statutory_deadline": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "401Unauthorized": { "description": "Authentication credentials missing or invalid. Provide Authorization: Bearer or X-Postal-Key header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/health": { "get": { "operationId": "postal_check_health", "summary": "Check PostalAgent service health", "description": "Verifies that the PostalAgent core ingress mailroom gateway is operational and reports system metrics.", "security": [], "responses": { "200": { "description": "Service is operational", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "postalagent-core" }, "version": { "type": "string", "example": "1.0.0" }, "total_mail_items": { "type": "integer", "example": 7 }, "default_driver": { "type": "string", "example": "sovereign_core" } } } } } } } } }, "/api/v1/cmra/providers": { "get": { "operationId": "postal_list_cmra_providers", "summary": "List CMRA physical address facilities and pricing tiers", "description": "Retrieve available Commercial Mail Receiving Agency (CMRA) physical locations and subscription plans ($25 Starter Mailroom, $49 Founder & Executive, $99 Multi-State Network).", "security": [], "responses": { "200": { "description": "List of certified CMRA physical network providers and pricing tiers." } } } }, "/api/v1/notary/schedule": { "post": { "operationId": "postal_schedule_notary", "summary": "Schedule Remote Online Notary for USPS Form 1583", "description": "Pre-fills mandatory USPS Form 1583 and initiates a Remote Online Notary (RON) session via PostalAgent Statutory Notary Engine. Supports immediate instant queue or scheduled session.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "business_name", "applicant_name", "email" ], "properties": { "business_name": { "type": "string", "description": "Legal name of business entity" }, "applicant_name": { "type": "string", "description": "Full name of authorized founder/officer" }, "email": { "type": "string", "format": "email", "description": "Email address for session link and invite" }, "state": { "type": "string", "description": "State jurisdiction (e.g. DE, WY, CA, NV, NY)" }, "scheduled_time": { "type": "string", "description": "'instant' for immediate queue, or ISO 8601 datetime" }, "timezone": { "type": "string", "default": "America/New_York" }, "provider": { "type": "string", "enum": [ "instant", "scheduled" ], "default": "instant" } } } } } }, "responses": { "201": { "description": "Notary session successfully prepared and PMB address assigned." }, "400": { "description": "Invalid applicant parameters." } } } }, "/api/v1/onboarding/individual": { "post": { "operationId": "postal_start_individual_onboarding", "summary": "Start individual virtual mailbox onboarding with hosted Zero-PII KYC", "description": "Allocates a pending PMB address and initiates a hosted KYC identity verification session via PostalAgent Compliance Gateway. Returns a clean chat-friendly link without PostalAgent storing raw ID scans or biometrics.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "Full legal name of the individual applicant" }, "email": { "type": "string", "format": "email", "description": "Email address for onboarding link and notifications" }, "preferred_state": { "type": "string", "default": "DE", "description": "Preferred state jurisdiction for PMB address (DE, WY, CA, FL, TX)" }, "provider": { "type": "string", "enum": [ "standard", "expedited" ], "default": "standard", "description": "Hosted KYC verification routing mode" } } } } } }, "responses": { "201": { "description": "Individual onboarding session created with hosted KYC URL and pending PMB address." }, "400": { "description": "Missing parameters or raw PII violation." } } } }, "/api/v1/onboarding/assess-readiness": { "post": { "operationId": "postal_assess_business_readiness", "summary": "Assess commercial mailbox setup and legal prerequisites", "description": "Evaluates commercial virtual mailbox setup prerequisites including USPS Form 1583 notarization requirements, Secretary of State registered agent privacy status, IRS Form 8822-B address update requirements, and returns a structured onboarding roadmap.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_name": { "type": "string", "description": "Legal name of the business entity (e.g. NovaBio Technologies Inc.)" }, "formation_state": { "type": "string", "description": "State of formation or incorporation (e.g. DE, WY, CA)" }, "current_address": { "type": "string", "description": "Current physical or home address used during business formation" }, "entity_type": { "type": "string", "enum": [ "LLC", "C_CORP", "S_CORP", "SOLE_PROP", "PARTNERSHIP" ], "description": "Legal entity structure" }, "has_registered_agent": { "type": "boolean", "description": "Whether the business already has a professional commercial registered agent" } } } } } }, "responses": { "200": { "description": "Comprehensive business readiness assessment and onboarding action plan." } } } }, "/api/v1/onboarding/dialogue": { "post": { "operationId": "postal_start_onboarding_dialogue", "summary": "Initiate conversational onboarding dialogue", "description": "Returns tailored mailroom configuration, operational blueprints, RBAC routing suggestions, and recommended next tool calls based on user mission and team composition.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mission" ], "properties": { "mission": { "type": "string", "enum": [ "STARTUP_ADDRESS", "CHECKS_AND_AR", "LEGAL_DEFENSE", "PACKAGE_FORWARDING", "PRIVACY" ], "description": "Primary business use-case for the virtual mailbox" }, "team_roles": { "type": "array", "items": { "type": "string", "enum": [ "FOUNDER", "CPA_ACCOUNTANT", "LEGAL_COUNSEL", "OPS_TEAM" ] }, "description": "Key stakeholders receiving or acting on mail" } } } } } }, "responses": { "200": { "description": "Tailored onboarding configuration and recommended next actions." } } } }, "/api/v1/contacts/import": { "post": { "operationId": "postal_import_team_contacts", "summary": "Import team recipients and RBAC permissions (.vcf, CSV, JSON)", "description": "Bulk imports company team members, departments, and routing aliases from JSON, vCard (.vcf), or CSV. Configures role-based access control (Admin, Finance, Legal, Member) for automated mail distribution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "json", "vcf", "csv" ], "default": "json" }, "payload": { "type": "string", "description": "Raw string content for vCard (.vcf) or CSV formats" }, "contacts": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER_ADMIN", "FINANCE_DEPOSIT_APPROVER", "LEGAL_COUNSEL", "MEMBER_VIEWER" ] }, "department": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "mailing_address": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Contacts imported and RBAC matrix applied." }, "400": { "description": "Invalid format or missing payload." } } } }, "/api/v1/mail/digest": { "get": { "operationId": "postal_get_mailroom_digest", "summary": "Get real-time virtual mailbox summary and memory digest", "description": "Retrieves an executive summary of active virtual mailbox activity, including unread items, pending check deposits, active legal/tax statutory countdown clocks, and recent mail.", "responses": { "200": { "description": "Summary digest of virtual mailbox state", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "tenant_id": { "type": "string" }, "timestamp": { "type": "string" }, "summary": { "type": "object" }, "statutory_clocks": { "type": "array" }, "pending_checks": { "type": "array" }, "recent_mail": { "type": "array" } } } } } } } } }, "/api/v1/mail": { "get": { "operationId": "postal_list_mail", "summary": "List incoming mail items", "description": "Lists mail items received in your virtual mailbox. Filter by triage category or urgency priority level.", "parameters": [ { "name": "category", "in": "query", "description": "Filter by classified mail category", "schema": { "type": "string", "enum": [ "LEGAL_NOTICE_OR_SUMMONS", "TAX_OR_IRS", "BANK_OR_CHECK", "CORPORATE_COMPLIANCE", "MARKETING_OR_JUNK" ] } }, { "name": "priority", "in": "query", "description": "Filter by urgency priority level", "schema": { "type": "string", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] } }, { "name": "tenant_id", "in": "query", "description": "Optional tenant filter (admin only)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of mail items matching criteria", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MailItem" } } } } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" } } } }, "/api/v1/mail/{mail_id}": { "get": { "operationId": "postal_get_mail_item", "summary": "Get full details of a specific mail item", "description": "Retrieves high-resolution scan links, full OCR transcription, extracted entities, statutory deadlines, and action recommendations for a single envelope.", "parameters": [ { "name": "mail_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the mail item (e.g. postal_9401)" } ], "responses": { "200": { "description": "Detailed mail item record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailItem" } } } }, "404": { "description": "Mail item not found." } } } }, "/api/v1/mail/{mail_id}/scan": { "post": { "operationId": "postal_request_scan", "summary": "Request unsealing and interior 300 DPI duplex scan", "description": "Instructs the physical mailroom operator to open the sealed paper envelope and scan all interior pages at 300 DPI duplex with OCR text extraction.", "parameters": [ { "name": "mail_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interior scan ordered or already available." } } } }, "/api/v1/mail/{mail_id}/forward": { "post": { "operationId": "postal_request_forward", "summary": "Forward physical mail or check to a physical street address", "description": "Forwards original paper mail or negotiable check via USPS Priority Mail with a tamper-evident seal and 18 U.S.C. §§ 1702/1708 chain-of-custody logging.", "parameters": [ { "name": "mail_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination_address" ], "properties": { "destination_address": { "type": "string", "description": "Complete recipient name, street address, city, state, zip" } } } } } }, "responses": { "200": { "description": "Physical forwarding queued with tracking number and seal ID." } } } }, "/api/v1/mail/{mail_id}/deposit-check": { "post": { "operationId": "postal_request_check_deposit", "summary": "Programmatically deposit incoming check into bank account", "description": "Deposits an incoming negotiable physical check directly into client corporate bank account (Mercury, Brex, JPMorgan Chase, Relay). NOTE: Muse Sentinel approval is enforced before executing check deposits.", "x-sentinel-gated": true, "x-sentinel-risk-level": "HIGH", "x-sentinel-confirmation-prompt": "Are you sure you want to deposit this check of ${amount} into bank account ${bank_account_id}?", "parameters": [ { "name": "mail_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bank_account_id", "amount" ], "properties": { "bank_account_id": { "type": "string", "description": "Bank account ID destination" }, "amount": { "type": "string", "description": "Check dollar amount (e.g. '2450.00')" }, "human_auth_token": { "type": "string", "description": "Authorization token if amount >= $5,000" } } } } } }, "responses": { "200": { "description": "Check deposit successfully queued for settlement." }, "403": { "description": "Tier upgrade required or escrow confirmation needed." } } } }, "/api/v1/mail/{mail_id}/shred": { "post": { "operationId": "postal_request_shred", "summary": "Securely shred physical paper mail item", "description": "Destroys paper mail item. Autonomous shredding without human confirmation is strictly prohibited under 18 U.S.C. §§ 1702/1708. If human_auth_token is omitted, an interactive confirmation gate link is returned for human signature.", "x-sentinel-gated": true, "x-sentinel-risk-level": "CRITICAL", "x-sentinel-confirmation-prompt": "Federal law (18 U.S.C. §§ 1702/1708) requires explicit human authorization to destroy physical postal mail. Do you confirm shredding mail item {mail_id}?", "parameters": [ { "name": "mail_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "human_auth_token": { "type": "string", "description": "Cryptographic human authorization token" } } } } } }, "responses": { "200": { "description": "Shredding executed or human approval gate link returned." } } } }, "/api/v1/migrate/prepare": { "post": { "operationId": "postal_prepare_address_migration", "summary": "Prepare zero-risk commercial business address migration", "description": "Generates IRS Form 8822-B, Secretary of State amendment filings, and vendor change-of-address drafts with a time-bound cryptographic HMAC authorization token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "business_name", "old_address", "new_pmb_address" ], "properties": { "tenant_id": { "type": "string" }, "business_name": { "type": "string" }, "old_address": { "type": "string" }, "new_pmb_address": { "type": "string" }, "targets": { "type": "array", "items": { "type": "string", "enum": [ "IRS_8822B", "SECRETARY_OF_STATE", "BANK_ACCOUNTS", "VENDORS" ] } } } } } } }, "responses": { "200": { "description": "Migration diff prepared and human approval token generated." } } } }, "/api/v1/migrate/execute": { "post": { "operationId": "postal_execute_address_migration", "summary": "Execute prepared business address migration", "description": "Submits prepared filings and address updates. Requires valid human_approval_token from /api/v1/migrate/prepare.", "x-sentinel-gated": true, "x-sentinel-risk-level": "HIGH", "x-sentinel-confirmation-prompt": "Confirm execution of commercial address migration {migration_id}?", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "migration_id", "human_approval_token" ], "properties": { "migration_id": { "type": "string" }, "human_approval_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Address migration executed." }, "403": { "description": "Invalid or missing human authorization token." } } } }, "/api/v1/waitlist": { "post": { "operationId": "postal_join_waitlist", "summary": "Join PostalAgent priority mailroom waitlist", "description": "Registers a new business for early access priority onboarding, assigns priority queue number and referral code.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "company": { "type": "string" }, "state": { "type": "string", "default": "DE" }, "tier": { "type": "string", "default": "Core Mailroom ($89/mo)" }, "primary_use": { "type": "string" } } } } } }, "responses": { "200": { "description": "Already registered (idempotent)." }, "201": { "description": "Successfully registered on waitlist." } } } }, "/api/v1/system/version": { "get": { "operationId": "postal_check_system_status", "summary": "Check PostalAgent platform health, Alpha release tier, security patches, and changelog", "description": "Returns active platform version, alpha release tier, official security bulletins, CVE mitigations, and feature changelog.", "responses": { "200": { "description": "System status and version metadata" } } } }, "/api/v1/mail/certified/dispatch": { "post": { "operationId": "postal_dispatch_certified_mail", "summary": "Dispatch USPS Certified Mail or statutory filing with autonomous tracking", "description": "Autonomously prepares and dispatches physical USPS Certified Mail, IRS statutory filings, state amendments, or legal summons. Auto-registers 20-digit tracking and monitors delivery through to cryptographic Electronic Return Receipt (ERR).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient_name", "recipient_address", "document_type" ], "properties": { "recipient_name": { "type": "string" }, "recipient_address": { "type": "string" }, "sender_name": { "type": "string" }, "sender_address": { "type": "string" }, "document_type": { "type": "string", "example": "IRS_8822B" }, "raw_pdf_base64": { "type": "string" }, "restricted_delivery": { "type": "boolean", "default": false }, "return_receipt": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Certified mail successfully dispatched and tracking registered." }, "400": { "description": "Invalid dispatch payload." } } } }, "/api/v1/mail/certified/track/{trackingNumber}": { "get": { "operationId": "postal_track_certified_delivery", "summary": "Track real-time USPS Certified Mail delivery and get Electronic Return Receipt", "description": "Retrieves the carrier delivery lifecycle (DISPATCHED -> IN_TRANSIT -> OUT_FOR_DELIVERY -> DELIVERED), recipient signature, delivery facility, and cryptographic Electronic Return Receipt (ERR).", "parameters": [ { "name": "trackingNumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "20-digit USPS tracking number (e.g. 7020...)" }, { "name": "poll", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Set true to simulate or trigger immediate carrier status poll" } ], "responses": { "200": { "description": "Delivery tracking status and verification digest." }, "404": { "description": "Tracking number not found." } } } }, "/api/v1/mail/certified/dispatches": { "get": { "operationId": "postal_list_certified_dispatches", "summary": "List all tracked USPS Certified Mail dispatches for tenant", "description": "Returns array of active and completed certified mail dispatches, current delivery statuses, tracking numbers, and recipient details.", "responses": { "200": { "description": "List of certified mail dispatches." } } } }, "/api/v1/mail/signature/prepare": { "post": { "operationId": "postal_prepare_signature", "summary": "Prepare document for ESIGN/UETA digital signature and optional notary", "description": "Uploads and tokens a document for electronic signature collection and pre-dispatch notarization.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "signatories" ], "properties": { "title": { "type": "string" }, "signatories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } } }, "requires_notary": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "Document tokened and awaiting signatures." } } } }, "/api/v1/mail/signature/sign": { "post": { "operationId": "postal_sign_document", "summary": "Affix ESIGN/UETA compliant digital signature to prepared document", "description": "Records digital signature, IP address, user-agent, and SHA-256 integrity stamp. If notarization is required, routes to Remote Online Notary (RON) queue.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_id", "signatory_token", "full_name" ], "properties": { "document_id": { "type": "string" }, "signatory_token": { "type": "string" }, "full_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Signature affixed and document updated." } } } }, "/api/v1/billing/catalog": { "get": { "operationId": "postal_get_billing_catalog", "summary": "Get PostalAgent subscription plans and on-demand credit packs", "description": "Returns active subscription tiers (starter, founder, multistate) and pre-paid operational credit packs.", "responses": { "200": { "description": "Complete service rate card and billing catalog." } } } }, "/api/v1/billing/create-checkout-session": { "post": { "operationId": "postal_create_billing_checkout", "summary": "Generate 1-click Stripe embedded checkout session for subscription or credit pack", "description": "Creates authenticated Stripe checkout session URL for tenant onboarding or credit float replenishment.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "subscription", "credits" ] }, "plan_id": { "type": "string" }, "cadence": { "type": "string", "enum": [ "monthly", "annual" ], "default": "monthly" }, "pack_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "1-click Stripe checkout session generated." } } } }, "/api/v1/billing/credits/{tenantId}": { "get": { "operationId": "postal_get_credit_balance", "summary": "Retrieve tenant operational float credit ledger balance", "description": "Returns available credit balance in credits and USD equivalent.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current credit float balance." } } } } } }