version: "1.0.0"
title: "Square SMB postal operations desk"
description: "Use Goose with mailbox.bot MCP to draft, price, approve, sandbox-test, send, and track health inspection, food permit, city notice, fire/safety, license, application, insurance, landlord, vendor, negotiation, and other paper-heavy mail for Square-using SMBs."

parameters:
  - key: business_name
    input_type: string
    requirement: optional
    default: "the Square SMB"
    description: "Business name, such as Acme Cafe."
  - key: business_location
    input_type: string
    requirement: optional
    default: "the relevant Square location"
    description: "Square location name, address, or location ID if known."
  - key: agency_name
    input_type: string
    requirement: optional
    default: "County Health Department"
    description: "Agency, department, landlord, insurer, or recipient organization."
  - key: notice_type
    input_type: select
    requirement: optional
    default: "health_inspection_follow_up"
    description: "Type of correspondence to prepare."
    options:
      - health_inspection_follow_up
      - food_permit_renewal
      - city_notice_response
      - fire_safety_follow_up
      - business_license_follow_up
      - application_packet
      - negotiation_follow_up
      - signed_or_notarized_packet
      - insurance_or_landlord_packet
  - key: notice_or_permit_number
    input_type: string
    requirement: optional
    default: "unknown"
    description: "Inspection notice, permit, license, case, policy, or reference number."
  - key: deadline
    input_type: string
    requirement: optional
    default: "unknown"
    description: "Response deadline if known."
  - key: mail_class
    input_type: select
    requirement: optional
    default: "certified"
    description: "Use certified for inspection, permit, agency deadline, and dispute workflows."
    options:
      - first_class
      - certified
      - certified_return_receipt
  - key: use_sandbox
    input_type: boolean
    requirement: optional
    default: "true"
    description: "Create and advance a no-charge sandbox mail job before live mail."

extensions:
  - type: stdio
    name: mailbox-bot
    cmd: sh
    args:
      - "-lc"
      - "npx -y mcp-remote https://mailbox.bot/api/mcp --header \"Authorization: Bearer $MAILBOX_BOT_API_KEY\""
    timeout: 300
    env_keys:
      - MAILBOX_BOT_API_KEY
    description: "mailbox.bot MCP tools for postal mail cost preview, approval-gated sends, webhooks, proof, and sandbox lifecycle testing."
    available_tools:
      - get_mailbox_md
      - update_webhook
      - send_outbound_mail
      - list_outbound_mail
      - get_outbound_mail
      - create_test_outbound_mail
      - advance_test_outbound_mail

activities:
  - "message: Use this recipe when a Square SMB needs to respond to an inspection, permit, city notice, license renewal, application, insurance request, landlord packet, vendor packet, negotiation, signed packet, or other postal workflow. It is approval-first and sandbox-first."
  - "Prepare a health inspection correction follow-up for {{ business_name }} at {{ business_location }}."
  - "Prepare a food permit renewal follow-up for {{ agency_name }} with deadline {{ deadline }}."
  - "Sandbox-test a certified mail lifecycle and confirm submitted, mailed, and delivered webhook updates."

instructions: |
  You are an SMB postal operations agent. Your job is to help a Square-using SMB handle physical mail correspondence for health inspections, food permits, city notices, fire/safety inspections, business licenses, applications, appeals, insurance requests, landlord packets, vendor compliance packets, negotiation letters, signed document bundles, notarized forms, and similar paper-heavy operating workflows.

  Treat mailbox.bot as the physical-world execution and proof layer. Keep the operator in control of risky actions.

  Required safety behavior:
  - Do not send live postal mail until the human explicitly approves.
  - Use dry_run=true before any live send.
  - Use requires_approval=true for certified mail, agency deadlines, inspection responses, permit packets, applications, negotiations, signed/notarized document bundles, disputes, and anything with legal or compliance risk.
  - Prefer certified mail for inspection corrections, permit deadlines, agency disputes, required-response notices, appeals, formal offers, and mailed application packets.
  - Ask for missing agency address, attention line, notice number, deadline, enclosure list, signature/notary/check requirements, business legal name, or return-address details instead of guessing.
  - Store workflow metadata on every mailbox.bot mail job.

  Recommended metadata:
  - source: goose
  - integration: square
  - workflow: {{ notice_type }}
  - business_name: {{ business_name }}
  - square_location: {{ business_location }}
  - agency: {{ agency_name }}
  - notice_or_permit_number: {{ notice_or_permit_number }}
  - deadline: {{ deadline }}
  - correlation_id: goose-compliance-mail

  If use_sandbox is true:
  - Call create_test_outbound_mail first with representative metadata and mail_class={{ mail_class }}.
  - Call advance_test_outbound_mail until the test job reaches delivered.
  - Explain that this proves the webhook/status loop without billing or facility fulfillment.

  When preparing a real outbound mail draft:
  - Read available notice/PDF/email/user context.
  - Extract sender agency, recipient/attention line, notice number, inspection or permit date, correction items, deadline, mailing address, and required enclosures.
  - Draft a concise professional letter.
  - Use send_outbound_mail with dry_run=true to return cost, page count, and mail class.
  - Present an approval checklist before live send.

prompt: |
  Prepare an approval-ready postal mail workflow for {{ business_name }}.

  Business/location context: {{ business_location }}
  Recipient/agency: {{ agency_name }}
  Workflow type: {{ notice_type }}
  Notice or permit number: {{ notice_or_permit_number }}
  Deadline: {{ deadline }}
  Preferred mail class: {{ mail_class }}
  Use sandbox first: {{ use_sandbox }}

  Start by identifying missing facts. If enough information is present, create the draft letter, attach recommended mailbox.bot metadata, run a dry-run cost preview, and provide an approval checklist. If sandbox is enabled, create and advance a test outbound mail job before proposing live mail.

response:
  json_schema:
    type: object
    properties:
      summary:
        type: string
      missing_facts:
        type: array
        items:
          type: string
      draft_letter:
        type: string
      recommended_mail_class:
        type: string
      mailbox_metadata:
        type: object
      sandbox_result:
        type: object
      dry_run_result:
        type: object
      approval_checklist:
        type: array
        items:
          type: string
      next_action:
        type: string
    required:
      - summary
      - missing_facts
      - recommended_mail_class
      - mailbox_metadata
      - approval_checklist
      - next_action