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

# Add recipients to a project

> Add one or more recipients to an existing project. Recipients will be added as contacts and associated with the project. If a recipient with the same internal_id already exists, they will be updated instead.



## OpenAPI

````yaml /openapi.yaml post /projects/add-recipients/{projectUuid}
openapi: 3.1.0
info:
  title: Postable API
  version: 1.0.0
  description: API for managing contacts and groups in Postable
servers:
  - url: https://www.postable.com/api/v1
    description: API base URL
security: []
paths:
  /projects/add-recipients/{projectUuid}:
    parameters:
      - name: projectUuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: UUID of the project to add recipients to
        example: 123e4567-e89b-12d3-a456-426614174000
    post:
      summary: Add recipients to a project
      description: >-
        Add one or more recipients to an existing project. Recipients will be
        added as contacts and associated with the project. If a recipient with
        the same internal_id already exists, they will be updated instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/Recipient'
              required:
                - recipients
            example:
              recipients:
                - first_name: John
                  last_name: Doe
                  address: 123 Main St
                  city: Anytown
                  state: CA
                  zip: '12345'
                  country: United States
                  email: john@example.com
                  internal_id: CUST-001
                - first_name: Jane
                  last_name: Smith
                  address: 456 Oak Ave
                  apt: Suite 100
                  city: Othertown
                  state: NY
                  zip: '67890'
                  country: United States
                  override_message: Custom message for Jane
      responses:
        '200':
          description: Recipients added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AddRecipientsResult'
        '403':
          description: Unauthorized to update this project
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: You do not have permission to update this project
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Project not found
      security:
        - sanctum: []
components:
  schemas:
    Recipient:
      type: object
      properties:
        first_name:
          type: string
          description: First name of the recipient
        last_name:
          type: string
          description: Last name of the recipient (optional)
        company:
          type: string
          description: Company name (optional)
        address:
          type: string
          description: Street address
        apt:
          type: string
          description: Apartment, suite, or unit number (optional)
        city:
          type: string
          description: City
        state:
          type: string
          description: State or province
        zip:
          type: string
          description: ZIP or postal code
        country:
          type: string
          description: Country
        email:
          type: string
          format: email
          description: Email address (optional)
        internal_id:
          type: string
          maxLength: 20
          description: Your internal identifier for this recipient (optional)
        override_message:
          type: string
          description: Custom message to override project default (optional)
        override_signoff:
          type: string
          description: Custom signoff to override project default (optional)
        scheduled_delivery_date:
          type: string
          format: date
          description: Scheduled delivery date (must be in the future, optional)
        sender:
          $ref: '#/components/schemas/RecipientSender'
      required:
        - first_name
        - address
        - city
        - state
        - zip
        - country
    AddRecipientsResult:
      type: object
      properties:
        message:
          type: string
          description: Summary message
        contacts_updated:
          type: integer
          description: Number of existing contacts that were updated
        contacts_created:
          type: integer
          description: Number of new contacts that were created
    RecipientSender:
      type: object
      description: >
        Per-recipient sender (return address) override. When provided, the
        printed card uses this sender/return address in the corner instead of
        the account-level return address. Omit to use the account default.
      properties:
        name:
          type: string
          maxLength: 200
          description: >-
            Sender name. Either name or company is required when sender is
            provided.
        company:
          type: string
          maxLength: 60
          description: >-
            Sender company. Either name or company is required when sender is
            provided.
        address:
          type: string
          maxLength: 100
          description: Sender street address
        apt:
          type: string
          maxLength: 50
          description: Sender apartment, suite, or unit number (optional)
        city:
          type: string
          maxLength: 25
          description: Sender city
        state:
          type: string
          maxLength: 60
          description: Sender state or province (required for United States addresses)
        zip:
          type: string
          maxLength: 11
          description: Sender ZIP or postal code (required for United States addresses)
        country:
          type: string
          description: Sender country
      required:
        - address
        - city
        - country
  securitySchemes:
    sanctum:
      type: http
      scheme: bearer
      bearerFormat: JWT

````