> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.arb.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a mailing request

> Creates a mailing with PDF attachment to be delivered to a recipient address. Accepts a multipart form with mailing parameters and PDF file. Requires postal.mail.sender permission.



## OpenAPI

````yaml api-reference/postal.yaml post /mailings/create
openapi: 3.0.3
info:
  title: postal
  description: >-
    The Postal Service is the service that mails letters on behalf of other
    services. It abstracts away the underlying mail provider, ensuring
    consistent and reliable delivery.
  version: 1.0.0
servers:
  - url: https://postal.platform.arb.inc
security: []
tags:
  - name: /
  - name: mailings
paths:
  /mailings/create:
    post:
      tags:
        - mailings
      summary: Create a mailing request
      description: >-
        Creates a mailing with PDF attachment to be delivered to a recipient
        address. Accepts a multipart form with mailing parameters and PDF file.
        Requires postal.mail.sender permission.
      operationId: createMailing
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - parameters
                - pdf
              properties:
                parameters:
                  type: string
                  description: JSON-encoded object containing mailing parameters
                  example: >-
                    {"mailType":"certified","mailingConfig":{},"idempotencyKey":"2720f109-0caf-4c62-af22-5d08c853711c","recipient":{"name":"John
                    Doe","address":"123 Main St","city":"New
                    York","state":"NY","zipcode":"10001"}}
                pdf:
                  type: string
                  format: binary
                  description: PDF file to be mailed (maximum 10 MiB)
            encoding:
              parameters:
                contentType: application/json
              pdf:
                contentType: application/pdf
      responses:
        '200':
          description: Mailing successfully queued for delivery
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier for the created mailing
                    example: a79f3a6b-3fa8-4007-b9b7-824cb8ca7031
        '409':
          description: Mailing with the same idempotency key already exists
          content:
            text/plain:
              schema:
                type: string
                example: Mailing already exists
        '410':
          description: PDF file exceeds maximum allowed size
          content:
            text/plain:
              schema:
                type: string
                example: PDF is too large
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      description: access token
      scheme: bearer
      bearerFormat: JWT

````