> ## Documentation Index
> Fetch the complete documentation index at: https://developer.finogates.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mail a Document (Full Payload)

> Mail a document **you supply** with the recipient sent inline - everything in one call, nothing registered beforehand. The counterpart to `POST /document-mailing` for a one-off recipient you do not keep.

This shape has no `payee_id` to anchor ownership on. Send `sender` to type a one-off sender identity — that address prints on the label instead of the facility address. Omit it and the owner (and mailing label) default to your platform's own admin/master account. Do not send `user_id`; it is resolved automatically either way.

This is a `multipart/form-data` request: `document` (and optional `attachments`) are file parts, and `payload` is this JSON, encoded as a string, alongside them.

Sample `payload`:
```json
{
  "sender": {
    "name": "Jane Roe",
    "email": "jane@example.com",
    "phone": "+12125550123",
    "line_1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "recipient": {
    "name": "Dana Reed",
    "line_1": "456 Oak Ave",
    "city": "Denver",
    "state": "CO",
    "zip": "80202",
    "country": "US"
  },
  "mail_type": "usps_ground_advantage",
  "currency": "USD",
  "description": "Signed lease agreement",
  "idempotency_key": "doc-mail-2026-08-24-002"
}
```

`sender` is optional — omit it entirely to mail as your platform's own admin/master account instead of a typed one-off sender.



## OpenAPI

````yaml POST /v1/platform/payments/document-mailing/global
openapi: 3.1.0
info:
  title: Finogate Platform API v1
  version: 0.1.0
servers:
  - url: https://api-sandbox.finogates.com
    description: Sandbox
  - url: https://api.finogates.com
    description: Production
security: []
tags:
  - name: auth
  - name: users
  - name: payees
  - name: verification
  - name: bank accounts
  - name: card processing
  - name: digital-assets
  - name: international
  - name: fees
  - name: onboarding
  - name: pending-applications
  - name: wallets
  - name: payments
  - name: document mailing
  - name: merchant onboarding
  - name: catalog
  - name: webhooks
  - name: screening
  - name: Platform - File Scanning
  - name: phone-numbers
  - name: sms
  - name: calls
  - name: listings
  - name: Card Transfers
  - name: embed-tokens
paths:
  /v1/platform/payments/document-mailing/global:
    post:
      tags:
        - document mailing
      summary: Mail a Document (full payload)
      description: >-
        Mail a document **you supply** with the recipient sent inline -
        everything in one call, nothing registered beforehand. The counterpart
        to `POST /document-mailing` for a one-off recipient you do not keep.


        This shape has no `payee_id` to anchor ownership on. Send `sender` to
        type a one-off sender identity — that address prints on the label
        instead of the facility address. Omit it and the owner (and mailing
        label) default to your platform's own admin/master account. Do not send
        `user_id`; it is resolved automatically either way.


        This is a `multipart/form-data` request: `document` (and optional
        `attachments`) are file parts, and `payload` is this JSON, encoded as a
        string, alongside them.


        Sample `payload`:

        ```json

        {
          "sender": {
            "name": "Jane Roe",
            "email": "jane@example.com",
            "phone": "+12125550123",
            "line_1": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "zip": "78701",
            "country": "US"
          },
          "recipient": {
            "name": "Dana Reed",
            "line_1": "456 Oak Ave",
            "city": "Denver",
            "state": "CO",
            "zip": "80202",
            "country": "US"
          },
          "mail_type": "usps_ground_advantage",
          "currency": "USD",
          "description": "Signed lease agreement",
          "idempotency_key": "doc-mail-2026-08-24-002"
        }

        ```


        `sender` is optional — omit it entirely to mail as your platform's own
        admin/master account instead of a typed one-off sender.
      operationId: >-
        create_document_shipping_global_v1_platform_payments_document_mailing_global_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_document_shipping_global_v1_platform_payments_document_mailing_global_post
        required: true
      responses:
        '201':
          description: The mailed document, straight after create.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonResponse_DocumentShippingRead_'
              example:
                status_code: 201
                data:
                  document_shipping_id: 9b1e6c2a-4f3d-4a8b-9c7e-2d5f1a6b3c4d
                  payment_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  status: pending
                  mail_type: usps_ground_advantage
                  amount: 0
                  fee_amount: 12.35
                  total_amount: 12.35
                  currency: USD
                  recipient:
                    name: Dana Reed
                    phone: '+13035550188'
                    line_1: 456 Oak Ave
                    line_2: Suite 200
                    city: Denver
                    state: CO
                    zip: '80202'
                    country: US
                  description: Q3 invoice packet
                  invoice_number: INV-10432
                  intent_status: pending_review
                  created_at: '2026-08-24T14:30:00Z'
                  updated_at: '2026-08-24T14:30:00Z'
                  attachments:
                    - id: 7c4d2e1a-8b3f-4d6c-9a1e-5f2b3c4d5e6f
                      file_name: remittance_advice.pdf
                      page_count: 2
                      byte_size: 184320
                      ordinal: 0
                  attachment_page_count: 2
                  attachment_fee: 0.5
                  document_page_count: 10
                  document_fee: 4.9
                  shipping_fee: 6.95
                  carrier_cost: 5.2
                  markup: 1.75
                query_generated_time: 1712847600000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - _AuthenticatedBearer: []
components:
  schemas:
    Body_create_document_shipping_global_v1_platform_payments_document_mailing_global_post:
      properties:
        payload:
          type: string
          title: Payload
          description: JSON-encoded DocumentShippingGlobalCreate.
        document:
          type: string
          format: binary
          title: Document
          description: The document itself, as a PDF (<= 7MB).
        attachments:
          items:
            type: string
            format: binary
          type: array
          title: Attachments
          description: Extra PDFs mailed with the document. Charged per page.
          default: []
      type: object
      required:
        - payload
        - document
      title: >-
        Body_create_document_shipping_global_v1_platform_payments_document_mailing_global_post
    CommonResponse_DocumentShippingRead_:
      properties:
        status_code:
          type: integer
          title: Status Code
          description: HTTP status code for the response.
        data:
          $ref: '#/components/schemas/DocumentShippingRead'
          description: Payload or error details.
        query_generated_time:
          type: integer
          title: Query Generated Time
          description: >-
            UTC timestamp (milliseconds since epoch) when response was
            generated.
      type: object
      required:
        - status_code
        - data
        - query_generated_time
      title: CommonResponse[DocumentShippingRead]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DocumentShippingRead:
      properties:
        document_shipping_id:
          type: string
          format: uuid
          title: Document Shipping Id
          examples:
            - 9b1e6c2a-4f3d-4a8b-9c7e-2d5f1a6b3c4d
        payment_id:
          type: string
          format: uuid
          title: Payment Id
          examples:
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          title: Status
          examples:
            - mailed
        mail_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mail Type
          examples:
            - usps_ground_advantage
        amount:
          type: number
          title: Amount
          examples:
            - 0
        fee_amount:
          type: number
          title: Fee Amount
          default: 0
          examples:
            - 8.45
        total_amount:
          type: number
          title: Total Amount
          examples:
            - 8.45
        currency:
          type: string
          title: Currency
          examples:
            - USD
        recipient:
          $ref: '#/components/schemas/DocumentShippingRecipient'
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          examples:
            - Q3 invoice packet
        invoice_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Invoice Number
          examples:
            - INV-10432
        intent_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent Status
          examples:
            - succeeded
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        attachments:
          items:
            $ref: '#/components/schemas/DocumentMailingAttachmentRead'
          type: array
          title: Attachments
        attachment_page_count:
          type: integer
          title: Attachment Page Count
          default: 0
          examples:
            - 3
        attachment_fee:
          type: number
          title: Attachment Fee
          default: 0
          examples:
            - 0.75
        document_page_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Document Page Count
          examples:
            - 10
        document_fee:
          anyOf:
            - type: number
            - type: 'null'
          title: Document Fee
          examples:
            - 4.9
        shipping_fee:
          anyOf:
            - type: number
            - type: 'null'
          title: Shipping Fee
          examples:
            - 6.2
        carrier_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Carrier Cost
          examples:
            - 4.5
        markup:
          anyOf:
            - type: number
            - type: 'null'
          title: Markup
          examples:
            - 1.7
        tracking:
          anyOf:
            - $ref: '#/components/schemas/DocumentShippingTrackingSummary'
            - type: 'null'
      type: object
      required:
        - document_shipping_id
        - payment_id
        - status
        - amount
        - total_amount
        - currency
        - recipient
      title: DocumentShippingRead
      description: >-
        A document-shipping's current state (sidecar detail over the payment
        intent).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    DocumentShippingRecipient:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          examples:
            - Jane Smith
        phone:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          title: Phone
          examples:
            - '+12125550123'
        line_1:
          type: string
          maxLength: 255
          minLength: 1
          title: Line 1
          examples:
            - 123 Main St
        line_2:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Line 2
          examples:
            - Apt 4B
        city:
          type: string
          maxLength: 120
          minLength: 1
          title: City
          examples:
            - Austin
        state:
          type: string
          maxLength: 120
          minLength: 1
          title: State
          examples:
            - TX
        zip:
          type: string
          maxLength: 20
          minLength: 1
          title: Zip
          examples:
            - '78701'
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          default: US
          examples:
            - US
      type: object
      required:
        - name
        - line_1
        - city
        - state
        - zip
      title: DocumentShippingRecipient
      description: The postal address the physical check is mailed to.
    DocumentMailingAttachmentRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          examples:
            - 7c4d2e1a-8b3f-4d6c-9a1e-5f2b3c4d5e6f
        file_name:
          type: string
          title: File Name
          examples:
            - remittance_advice.pdf
        page_count:
          type: integer
          title: Page Count
          default: 1
          examples:
            - 2
        byte_size:
          type: integer
          title: Byte Size
          default: 0
          examples:
            - 184320
        ordinal:
          type: integer
          title: Ordinal
          default: 0
          examples:
            - 0
      type: object
      required:
        - id
        - file_name
      title: DocumentMailingAttachmentRead
      description: One PDF mailed alongside the check.
    DocumentShippingTrackingSummary:
      properties:
        trackable:
          type: boolean
          title: Trackable
          description: >-
            Whether this shipping service produces a tracking barcode at all.
            False for letter services, which carry a postage indicia instead —
            there is no number to follow and there never will be, so absent
            tracking on one of those is not a fault.
        tracking_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Tracking Number
        carrier:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier
          description: Carrier key.
          examples:
            - fedex
        carrier_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier Label
          description: Carrier name, for display.
          examples:
            - FedEx
        service:
          anyOf:
            - type: string
            - type: 'null'
          title: Service
          description: The shipping service bought.
          examples:
            - FedEx Standard Overnight
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: >-
            Current delivery stage, taken from the most recent scan — not the
            furthest stage reached. A parcel that hit an exception after going
            out for delivery reads `exception`, because that is what is true
            now. Null when no scans have been recorded yet.
          examples:
            - out_for_delivery
        status_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Label
          description: Display form of `status`.
          examples:
            - Out for delivery
        shipped_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Shipped At
          description: When the shipping label was purchased.
        estimated_delivery_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Estimated Delivery At
          description: >-
            The carrier's own delivery estimate, not a commitment from us.
            Present it as the carrier's estimate wherever it is shown.
        delivered_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Delivered At
          description: >-
            When the carrier confirmed delivery. Delivery means the envelope
            reached the address — not that its contents were acted on.
        delivered_to:
          anyOf:
            - type: string
            - type: 'null'
          title: Delivered To
          description: >-
            Who the carrier recorded as accepting the parcel. Null until
            delivered, and on services that capture no signature — most of them
            — so its absence is never evidence of a problem.
          examples:
            - J.SMITH
        synced_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Synced At
          description: >-
            When we last successfully read this shipment's status from the
            carrier. Show it, so how fresh the page is stays visible rather than
            assumed.
        carrier_tracking_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier Tracking Url
          description: The carrier's own tracking page for this shipment.
      type: object
      required:
        - trackable
      title: DocumentShippingTrackingSummary
      description: |-
        Where a shipment is, without the scan list.

        Nested into shipment detail and list responses so a caller rendering a
        status column never has to fetch the full timeline per row.
  securitySchemes:
    _AuthenticatedBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /v1/platform/auth/token

````