---
openapi: 3.0.1
info:
  title: Noted API V2
  version: '2'
  description: |
    REST API for sending handwritten cards, managing reusable assets, and retrieving scan activity.

    Build against the Noted API to send one-off cards, run larger mailings, manage assets, and retrieve recent scan events.

    ## Base URL
    `https://live.simplynoted.com`

    ## Authentication
    Send `x-user-id` and `x-api-key` on every request.

    If your integration has delegated access within an authorized account, you can also send `x-actor-id`.

    ## Common workflow
    1. Create or select a sender profile, card, message, and recipient data.
    2. Use the single-card endpoint for one recipient.
    3. Use the mailings endpoints for bulk sends and scan tracking.

    ## Notes
    - Requests are scoped to the account tied to the provided user.
    - Assets can be prepared in the dashboard ahead of time or managed through the API where supported.
servers:
- url: https://live.simplynoted.com
  description: Production
security:
- ApiUserId: []
  ApiKey: []
tags:
- name: Single Cards
  description: Send a single card to an individual or household
- name: Mailings
  description: Sending multi-card mailings and managing all mailings
- name: Assets
  description: List the reusable assets available to the current account
- name: Integrations
  description: Connect users for partner services.
- name: Messages
  description: Defines the copy for mailings, supports merge tags.
- name: Lists
  description: Operations related to lists
- name: Cards
  description: Operations for creating and retrieving card designs
- name: Tokens
  description: Operations related to user tokens
- name: Sender Profiles
  description: Operations for managing sender profiles
- name: Handwriting Styles
  description: Operations for retrieving available handwriting styles
- name: Webhooks
  description: |
    Receive JSON notifications when mail is delivered or QR codes are scanned. Webhooks are available on the Developer ($97/month) and Unlimited ($497/month) plans.

    You can create and manage webhooks from `/account/webhooks` in the dashboard or through the API endpoints in this section.

    ## Event types

    | Event | Description |
    | --- | --- |
    | `delivery` | Fires when a mail piece's USPS tracking status changes (`sent`, `in_transit`, `delivered`, `fail`). |
    | `qr_scan` | Fires when a recipient scans the QR code printed on their card. |

    ## Payload format

    Both events send a JSON body via `POST`. Example for a `delivery` event:

    ```json
    {
      "id": "<barcode-uuid>",
      "mailing_id": "<mailing-uuid>",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "address": "123 Main St, Portland, OR, 97201",
      "status": "delivered",
      "expected_delivery_date": "2026-04-20",
      "last_scan_date": "2026-04-20T14:22:10Z"
    }
    ```

    ## Request headers

    | Header | Value |
    | --- | --- |
    | `X-SimplyNoted-Event` | Event type (`delivery` or `qr_scan`) |
    | `X-SimplyNoted-Event-Id` | Unique event ID (format: `evt_<hex>`) — use for idempotency |
    | `X-SimplyNoted-Delivery-Id` | Delivery attempt ID — for debugging |
    | `X-SimplyNoted-Timestamp` | Unix epoch seconds when the request was sent |
    | `X-SimplyNoted-Signature` | (Optional, if signing enabled) HMAC-SHA256 signature |

    ## HMAC signing (optional)

    If you enable signing on a webhook, we include an `X-SimplyNoted-Signature` header. The signature is computed as:

    ```
    hmac_sha256(secret, "{timestamp}.{request_body}")
    ```

    Example verification in Ruby:

    ```ruby
    expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{body}")
    raise "Invalid signature" unless Rack::Utils.secure_compare(expected, signature_header)
    ```

    ## Retries

    We deliver each event with up to 3 attempts total (1 initial + 2 retries). Retry schedule: immediate, then 5 minutes, then 30 minutes.

    - `2xx` response → success, no retries
    - `4xx` response (except `408` and `429`) → permanent failure, no retries
    - `5xx` response, `408`, `429`, timeout, or network error → retried

    ## Auto-disable

    A webhook that fails 10 consecutive events is automatically disabled and the owner is notified via email. You can re-enable it from the account page.

    Verified partner requests can manage webhooks on behalf of authorized users by supplying `X-Actor-Id` alongside the standard API headers.
paths:
  "/api/v2/tokens/balance":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: getTokenBalance
      summary: Get Token Balance
      tags:
      - Tokens
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_balance:
                    type: integer
                    description: The current spendable token balance of the user
                    example: 100
                  standard_token_balance:
                    type: integer
                    description: Standard credits available on the account
                    example: 100
                  unlimited_token_balance:
                    type: integer
                    description: Unlimited-plan credits currently held on the account
                    example: 1200
                  postcard_token_balance:
                    type: integer
                    description: Current spendable postcard credit balance for the user's plan
                    example: 80
                  standard_postcard_token_balance:
                    type: integer
                    description: Standard postcard credits available on the account
                    example: 80
                  unlimited_postcard_token_balance:
                    type: integer
                    description: Unlimited-plan postcard credits currently held on the account
                    example: 900
              examples:
                default:
                  "$ref": "#/components/examples/token_balance_response"
        '401':
          description: unauthorized
  "/api/v2/assets":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listAssets
      summary: List Assets
      tags:
      - Assets
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page for each asset collection, defaults to 100 and caps at 100
        schema:
          type: integer
      responses:
        '200':
          description: assets found
          content:
            application/json:
              schema:
                type: object
                properties:
                  assets:
                    type: object
                    properties:
                      sender_profiles:
                        type: array
                        items:
                          "$ref": "#/components/schemas/sender_profiles"
                      cards:
                        type: array
                        items:
                          "$ref": "#/components/schemas/cards"
                      lists:
                        type: array
                        items:
                          "$ref": "#/components/schemas/lists"
                      messages:
                        type: array
                        items:
                          "$ref": "#/components/schemas/messages"
                  pagination:
                    type: object
                    properties:
                      sender_profiles:
                        "$ref": "#/components/schemas/pagination_metadata"
                      cards:
                        "$ref": "#/components/schemas/pagination_metadata"
                      lists:
                        "$ref": "#/components/schemas/pagination_metadata"
                      messages:
                        "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/assets_response"
        '401':
          description: unauthorized
  "/api/v2/integrations/verify":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    post:
      operationId: verifyIntegration
      summary: Verify Integration
      tags:
      - Integrations
      responses:
        '200':
          description: integration verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  integration:
                    type: object
                    properties:
                      user_id:
                        type: string
                      status:
                        type: string
        '422':
          description: invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: integration not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - integration
              properties:
                integration:
                  type: object
                  required:
                  - integration_provider_id
                  - connect_code
                  - user_id
                  properties:
                    integration_provider_id:
                      type: string
                      description: Integration Provider ID
                    connect_code:
                      type: string
                      description: Code provided in connect request
                    user_id:
                      type: string
                      description: ID of the user to be verified
            examples:
              request_example_1:
                summary: Verify Integration
                value:
                  integration:
                    integration_provider_id: e7810833-75c0-4ff6-b7f0-b6e822b141f0
                    connect_code: e2723e49d35f2e7595ad
                    user_id: fa742d9e-d099-43cd-bd4f-367ed6f23e7c
  "/api/v2/lists":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listRecipientLists
      summary: List Recipient Lists
      tags:
      - Lists
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 500 and caps at 500
        schema:
          type: integer
      responses:
        '200':
          description: lists found
          content:
            application/json:
              schema:
                type: object
                properties:
                  lists:
                    type: array
                    items:
                      "$ref": "#/components/schemas/lists"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/lists_response"
        '401':
          description: unauthorized
    post:
      operationId: createRecipientList
      summary: Create Recipient List
      tags:
      - Lists
      responses:
        '202':
          description: List accepted, processing contacts
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/list_write_response"
              examples:
                default:
                  "$ref": "#/components/examples/list_created_response"
        '401':
          description: unauthorized
        '422':
          description: validation failed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_list_request"
            examples:
              default:
                "$ref": "#/components/examples/list_create_request"
  "/api/v2/lists/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      required: true
      description: List ID
      schema:
        type: string
    get:
      operationId: getRecipientList
      summary: Get Recipient List
      tags:
      - Lists
      responses:
        '200':
          description: list found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/list_detail_response"
              examples:
                default:
                  "$ref": "#/components/examples/list_response"
        '404':
          description: list not found
  "/api/v2/cards":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listCards
      summary: List Cards
      tags:
      - Cards
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 500 and caps at 500
        schema:
          type: integer
      - name: scope
        in: query
        required: false
        description: Set to `templates` to list global card templates instead of cards owned by the authenticated user.
        schema:
          type: string
          enum:
          - templates
      - name: category
        in: query
        required: false
        description: Optional category filter when `scope=templates`.
        schema:
          type: string
      - name: form_factor
        in: query
        required: false
        description: Optional card form factor filter.
        schema:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
      responses:
        '200':
          description: cards found
          content:
            application/json:
              schema:
                type: object
                properties:
                  cards:
                    type: array
                    items:
                      "$ref": "#/components/schemas/cards"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/cards_response"
        '400':
          description: invalid scope value
    post:
      operationId: createCard
      summary: Create Card
      tags:
      - Cards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_card_request"
            examples:
              default:
                "$ref": "#/components/examples/card_create_request"
      responses:
        '201':
          description: card created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/card_create_response"
              examples:
                default:
                  "$ref": "#/components/examples/card_created_response"
        '422':
          description: invalid request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_error_response"
  "/api/v2/cards/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      required: true
      description: Card ID
      schema:
        type: string
    get:
      operationId: getCard
      summary: Get Card
      tags:
      - Cards
      responses:
        '200':
          description: card found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/cards"
              examples:
                default:
                  "$ref": "#/components/examples/card_response"
        '404':
          description: card not found
        '429':
          description: card was created too recently to fetch
  "/api/v2/mailings":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listMailings
      summary: List Mailings
      tags:
      - Mailings
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 100 and caps at 100
        schema:
          type: integer
      - name: schedule_type
        in: query
        required: false
        description: Filter by the mailing's effective schedule type. Use scheduled for all one-time scheduled mailings, including mailings whose active submission carries the schedule even if the parent row is stale.
        schema:
          type: string
          enum:
          - immediate
          - scheduled
          - birthday
          - anniversary
      - name: schedule_status
        in: query
        required: false
        description: Filter by schedule lifecycle. scheduled returns all one-time scheduled mailings. active_scheduled returns one-time scheduled mailings that still have a pending submitted submission waiting for release.
        schema:
          type: string
          enum:
          - scheduled
          - active_scheduled
      responses:
        '200':
          description: mailings found
          content:
            application/json:
              schema:
                type: object
                properties:
                  mailings:
                    type: array
                    items:
                      "$ref": "#/components/schemas/mailing_summary"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/mailings_response"
        '401':
          description: unauthorized
    post:
      operationId: createMailing
      summary: Create Bulk Mailing
      tags:
      - Mailings
      responses:
        '201':
          description: mailing created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/mailing_create_response"
              examples:
                default:
                  "$ref": "#/components/examples/mailing_created_response"
        '422':
          description: invalid request, invalid schedule date, inaccessible list, or submission failure
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_error_response"
              examples:
                invalid_send_date:
                  "$ref": "#/components/examples/mailing_invalid_send_date_response"
                inaccessible_list:
                  "$ref": "#/components/examples/mailing_inaccessible_list_response"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_mailing_request"
            examples:
              request_example_1:
                summary: Mailings sent to multiple lists
                value:
                  mailing:
                    name: "April Outreach"
                    campaign_name: "Q2 Pipeline"
                    form_factor: jumbo_postcard
                    sender_profile_id: e307c2b1-3a28-49b5-b4d7-1139bed186f4
                    card_id: 84a450ad-00a6-4e41-811a-e3e409289a99
                    message_id: c4867882-edcd-45a1-be93-345172259e95
                    send_date: "2026-04-15"
                    list_ids:
                    - be0e551b-9213-4127-af29-f7f07bb42f04
                    - 0f37229e-96d3-4443-a282-6c9b8027804a
  "/api/v2/mailings/recent_scans":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listRecentScans
      summary: List All Recent Scans
      tags:
      - Mailings
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 100 and caps at 500
        schema:
          type: integer
      responses:
        '200':
          description: returns paginated recent scans
          content:
            application/json:
              schema:
                type: object
                required:
                - recent_scans
                - pagination
                properties:
                  recent_scans:
                    type: array
                    items:
                      "$ref": "#/components/schemas/recent_scan_item"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/recent_scans_response"
        '401':
          description: unauthorized
  "/api/v2/mailings/{id}/recent_scans":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      description: Mailing ID
      required: true
      schema:
        type: string
    get:
      operationId: listMailingRecentScans
      summary: List Recent Scans for a Mailing
      tags:
      - Mailings
      responses:
        '200':
          description: returns mailing-specific recent scans
          content:
            application/json:
              schema:
                type: object
                required:
                - recent_scans
                properties:
                  recent_scans:
                    type: array
                    items:
                      "$ref": "#/components/schemas/recent_scan_item"
              examples:
                default:
                  "$ref": "#/components/examples/mailing_recent_scans_response"
        '401':
          description: unauthorized
        '404':
          description: mailing not found
  "/api/v2/mailings/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    get:
      operationId: getMailing
      summary: Get Mailing Details
      tags:
      - Mailings
      responses:
        '200':
          description: mailing found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/mailing_detail_response"
              examples:
                default:
                  "$ref": "#/components/examples/mailing_response"
        '429':
          description: mailing was created too recently to fetch
    delete:
      operationId: deleteMailing
      summary: Delete Mailing
      tags:
      - Mailings
      responses:
        '200':
          description: mailing canceled
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/mailing_delete_response"
              examples:
                default:
                  "$ref": "#/components/examples/mailing_deleted_response"
        '422':
          description: mailing cannot be canceled
  "/api/v2/mailings/{id}/tracking":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      description: Mailing ID
      required: true
      schema:
        type: string
    get:
      operationId: getMailingTracking
      summary: Get Mailing Tracking
      tags:
      - Mailings
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of contacts to return per page. Defaults to 25 and caps at 25.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      responses:
        '200':
          description: tracking data found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/mailing_tracking_response"
              examples:
                default:
                  "$ref": "#/components/examples/mailing_tracking_response"
        '422':
          description: mailing has not been mailed yet or tracking fetch failed
  "/api/v2/messages":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listMessages
      summary: List Saved Messages
      tags:
      - Messages
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 500 and caps at 500
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      "$ref": "#/components/schemas/api_message_response"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/messages_response"
        '401':
          description: unauthorized
    post:
      operationId: createMessage
      summary: Create Saved Message
      tags:
      - Messages
      responses:
        '201':
          description: message created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_message_response"
              examples:
                default:
                  "$ref": "#/components/examples/message_response"
        '401':
          description: unauthorized
        '422':
          description: message validation failed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/message_validation_errors"
              examples:
                body too long:
                  "$ref": "#/components/examples/message_validation_errors"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_message_request"
            examples:
              new message:
                summary: Create a new message with or without merge tags.
                value:
                  message:
                    name: Hello
                    body: |-
                      Dear {{greeting}},
                       I hope you are well.
                       Best,
                      {{sender_first_name}}
  "/api/v2/messages/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    get:
      operationId: getMessage
      summary: Get Saved Message
      tags:
      - Messages
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_message_response"
              examples:
                default:
                  "$ref": "#/components/examples/message_response"
        '401':
          description: unauthorized
        '404':
          description: not found
    patch:
      operationId: updateMessage
      summary: Update Saved Message
      tags:
      - Messages
      responses:
        '200':
          description: message updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/api_message_response"
              examples:
                default:
                  "$ref": "#/components/examples/message_response"
        '404':
          description: not found
        '401':
          description: unauthorized
        '422':
          description: message validation failed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/message_validation_errors"
              examples:
                body too long:
                  "$ref": "#/components/examples/message_validation_errors"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_message_request"
    delete:
      operationId: deleteMessage
      summary: Delete Saved Message
      tags:
      - Messages
      responses:
        '200':
          description: message deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                default:
                  "$ref": "#/components/examples/message_deleted_response"
        '401':
          description: unauthorized
        '404':
          description: message not found
  "/api/v2/single_card_mailings":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    post:
      operationId: sendSingleCard
      summary: Send a Single Card
      tags:
      - Single Cards
      responses:
        '201':
          description: single card mailing created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/single_card_mailing_response"
              examples:
                default:
                  "$ref": "#/components/examples/single_card_mailing_response"
        '422':
          description: invalid request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/wrapped_single_card_mailing_request"
            examples:
              request_example_1:
                summary: Mail a single contact with a template message
                value:
                  single_card_mailing:
                    name: "Spring Check-in"
                    sender_profile_id: 1
                    card_id: 1
                    form_factor: jumbo_postcard
                    message_id: 1
                    contact:
                      first_name: John
                      last_name: Doe
                      street_1: 123 Main St
                      street_2: Apt 1
                      city: Anytown
                      state: NY
                      zipcode: '12345'
              request_example_2:
                summary: Mail a household with a template message
                value:
                  single_card_mailing:
                    name: "Household Follow-up"
                    sender_profile_id: 1
                    card_id: 1
                    message_id: 1
                    contact:
                      first_name: John
                      last_name: Doe
                      second_first_name: Jane
                      second_last_name: Doe
                      street_1: 123 Main St
                      street_2: Apt 1
                      city: Anytown
                      state: NY
                      zipcode: '12345'
              request_example_3:
                summary: Mail a household with custom message
                value:
                  single_card_mailing:
                    name: "Custom Household Note"
                    sender_profile_id: 1
                    card_id: 1
                    message_body: |-
                      Dear {{greeting}},
                       this is a test.
                       Best,
                      {{sender_first_name}}
                    contact:
                      first_name: John
                      last_name: Doe
                      second_first_name: Jane
                      second_last_name: Doe
                      street_1: 123 Main St
                      street_2: Apt 1
                      city: Anytown
                      state: NY
                      zipcode: '12345'
  "/api/v2/sender_profiles":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listSenderProfiles
      summary: List Sender Profiles
      tags:
      - Sender Profiles
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 500 and caps at 500
        schema:
          type: integer
      responses:
        '200':
          description: sender profiles found
          content:
            application/json:
              schema:
                type: object
                properties:
                  sender_profiles:
                    type: array
                    items:
                      $ref: "#/components/schemas/sender_profile_response"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/sender_profiles_response"
        '401':
          description: unauthorized
          
    post:
      operationId: createSenderProfile
      summary: Create Sender Profile
      tags:
      - Sender Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/wrapped_sender_profile_request"
      responses:
        '201':
          description: sender profile created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Sender profile created successfully"
                  sender_profile:
                    $ref: "#/components/schemas/sender_profile_response"
              examples:
                default:
                  "$ref": "#/components/examples/sender_profile_created_response"
        '422':
          description: unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string

  "/api/v2/sender_profiles/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: ID of the sender profile
    
    get:
      operationId: getSenderProfile
      summary: Get Sender Profile
      tags:
      - Sender Profiles
      responses:
        '200':
          description: sender profile found
          content:
            application/json:
              schema:
                type: object
                properties:
                  sender_profile:
                    $ref: "#/components/schemas/sender_profile_response"
              examples:
                default:
                  "$ref": "#/components/examples/sender_profile_response"
        '404':
          description: sender profile not found
          
    patch:
      operationId: updateSenderProfile
      summary: Update Sender Profile
      tags:
      - Sender Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/wrapped_sender_profile_request"
      responses:
        '200':
          description: sender profile updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Sender profile updated successfully"
                  sender_profile:
                    $ref: "#/components/schemas/sender_profile_response"
              examples:
                default:
                  "$ref": "#/components/examples/sender_profile_updated_response"
        '422':
          description: unprocessable entity
        '404':
          description: sender profile not found
          
    delete:
      operationId: deleteSenderProfile
      summary: Archive Sender Profile
      tags:
      - Sender Profiles
      responses:
        '200':
          description: sender profile archived; existing mailing history is retained
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Sender profile archived successfully"
              examples:
                default:
                  "$ref": "#/components/examples/sender_profile_archived_response"
        '422':
          description: cannot archive default sender profile
        '404':
          description: sender profile not found

  "/api/v2/handwriting_styles":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listHandwritingStyles
      summary: List Handwriting Styles
      tags:
      - Handwriting Styles
      parameters:
      - name: page
        in: query
        required: false
        description: Page number, defaults to 1
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Items per page, defaults to 500 and caps at 500
        schema:
          type: integer
      responses:
        '200':
          description: handwriting styles found
          content:
            application/json:
              schema:
                type: object
                properties:
                  handwriting_styles:
                    type: array
                    items:
                      $ref: "#/components/schemas/handwriting_style"
                  pagination:
                    "$ref": "#/components/schemas/pagination_metadata"
              examples:
                default:
                  "$ref": "#/components/examples/handwriting_styles_response"
        '401':
          description: unauthorized
  "/api/v2/webhooks":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    get:
      operationId: listWebhooks
      summary: List Webhooks
      tags:
      - Webhooks
      description: Returns all webhooks owned by the authenticated user, ordered by most recently created.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/webhook"
        '401':
          description: unauthorized
        '402':
          description: webhook access requires a Developer or Unlimited subscription
    post:
      operationId: createWebhook
      summary: Create Webhook
      tags:
      - Webhooks
      description: |
        Register a new webhook endpoint. The `target_url` must be an `https://` URL and must be unique for the account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/webhook_request"
            examples:
              default:
                summary: Subscribe to delivery and qr_scan events
                value:
                  target_url: https://example.com/webhooks/simplynoted
                  description: Production delivery hook
                  event_types:
                  - delivery
                  - qr_scan
      responses:
        '201':
          description: webhook created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/webhook"
        '401':
          description: unauthorized
        '402':
          description: webhook access requires a Developer or Unlimited subscription
        '422':
          description: validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
  "/api/v2/webhooks/{id}":
    parameters:
    - $ref: "#/components/parameters/XUserIdHeader"
    - $ref: "#/components/parameters/XApiKeyHeader"
    - $ref: "#/components/parameters/XActorIdHeader"
    - name: id
      in: path
      required: true
      description: ID of the webhook
      schema:
        type: string
    get:
      operationId: getWebhook
      summary: Get Webhook
      tags:
      - Webhooks
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/webhook"
        '401':
          description: unauthorized
        '402':
          description: webhook access requires a Developer or Unlimited subscription
        '404':
          description: webhook not found
    patch:
      operationId: updateWebhook
      summary: Update Webhook
      tags:
      - Webhooks
      description: Update the target URL, description, or subscribed event types on a webhook.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/webhook_update_request"
      responses:
        '200':
          description: webhook updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/webhook"
        '401':
          description: unauthorized
        '402':
          description: webhook access requires a Developer or Unlimited subscription
        '404':
          description: webhook not found
        '422':
          description: validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
    delete:
      operationId: deleteWebhook
      summary: Delete Webhook
      tags:
      - Webhooks
      responses:
        '204':
          description: webhook deleted
        '401':
          description: unauthorized
        '402':
          description: webhook access requires a Developer or Unlimited subscription
        '404':
          description: webhook not found
components:
  securitySchemes:
    ApiUserId:
      type: apiKey
      in: header
      name: X-User-Id
      description: The user ID for the account making the request.
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The API key for the user identified by X-User-Id.
  parameters:
    XUserIdHeader:
      name: X-User-Id
      in: header
      required: true
      description: The user ID for the account making the request.
      schema:
        type: string
        default: "{{userId}}"
    XApiKeyHeader:
      name: X-Api-Key
      in: header
      required: true
      description: The API key for the user identified by X-User-Id.
      schema:
        type: string
        default: "{{apiKey}}"
    XActorIdHeader:
      name: X-Actor-Id
      in: header
      required: false
      description: Optional delegated actor ID when a verified partner is acting on behalf of another user.
      schema:
        type: string
        default: "{{actorId}}"
  schemas:
    single_card_mailing:
      description: Create and send new single card mailing, must include either message_id
        or message_body.
      type: object
      required:
      - card_id
      - sender_profile_id
      - name
      - contact
      properties:
        card_id:
          type: integer
          example: 1
          description: id of the card
        message_id:
          type: integer
          example: 1
          description: id of the message, required if message_body is blank.
        message_body:
          type: string
          example: |-
            Dear {{greeting}},
             this is a test.
            Thanks,
             {{sender_first_name}}
          description: body of the message with merge tags, required if message_id is blank; maximum 500 non-whitespace Unicode characters. Each recipient's final message must also meet this limit after all merge tags are expanded. Spaces, tabs, and line breaks do not count.
        sender_profile_id:
          type: integer
          example: 1
          description: id of the sender profile
        name:
          type: string
          example: My Mailing
          description: name of the mailing
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: jumbo_postcard
          description: Optional card form factor. Defaults to the selected card's form factor, or folded_greeting_card when omitted.
        strict_contacts:
          type: boolean
          example: false
          description: when true, rejects contacts that require normalization
        schedule_type:
          type: string
          enum:
          - immediate
          - scheduled
          example: scheduled
          description: optional one-time schedule mode; defaults to immediate. Birthday and anniversary automations are supported by the bulk mailings endpoint, not single-card mailings.
        send_date:
          type: string
          format: date
          example: "2026-04-15"
          description: optional scheduled send date; aliases target_date
        target_date:
          type: string
          format: date
          example: "2026-04-15"
          description: optional scheduled send date
        contact:
          "$ref": "#/components/schemas/contact"
    wrapped_single_card_mailing_request:
      type: object
      required:
      - single_card_mailing
      properties:
        single_card_mailing:
          "$ref": "#/components/schemas/single_card_mailing"
    single_card_mailing_response:
      type: object
      properties:
        card_id:
          type: string
          example: "card-123"
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: jumbo_postcard
          description: Optional card form factor. Must match the selected card when provided; otherwise it is derived from the selected card.
        message_id:
          type: string
          example: "message-123"
          nullable: true
        sender_profile_id:
          type: string
          example: "sender-profile-123"
        name:
          type: string
          example: "Spring Check-in"
        schedule_type:
          type: string
          example: scheduled
        send_date:
          type: string
          example: "2026-04-15"
          nullable: true
        contact:
          "$ref": "#/components/schemas/contact"
        user_id:
          type: string
          example: "user-123"
        mailing_id:
          type: string
          example: "mailing-123"
    new_message:
      type: object
      properties:
        name:
          type: string
          example: My Message
          description: name of the message
        body:
          type: string
          example: |-
            Dear {{greeting}},
             this is a test.
            Thanks,
             {{sender_first_name}}
          description: body of the message with or without merge tags; maximum 500 non-whitespace Unicode characters. Each recipient's final message must also meet this limit after all merge tags are expanded. Spaces, tabs, and line breaks do not count.
      required:
      - name
      - body
    wrapped_message_request:
      type: object
      required:
      - message
      properties:
        message:
          "$ref": "#/components/schemas/new_message"
    contact:
      type: object
      description: Each custom_1 through custom_10 field is limited to 100 Unicode characters, including spaces, when creating or updating a contact. Oversized values are rejected, not truncated.
      properties:
        first_name:
          type: string
          example: John
          description: first name of the contact
        last_name:
          type: string
          example: Doe
          description: last name of the contact
        email:
          type: string
          example: John@example.com
          description: email of the contact
        phone:
          type: string
          example: 555-555-5555
          description: phone of the contact
        second_first_name:
          type: string
          example: Jane
          description: first name of the second contact
        second_last_name:
          type: string
          example: Doe
          description: last name of the second contact
        second_email:
          type: string
          example: Jane@example.com
          description: email of the second contact
        second_phone:
          type: string
          example: 555-555-5555
          description: phone of the second contact
        street_1:
          type: string
          example: 123 Main St
          description: street 1 of the contact
        street_2:
          type: string
          example: Apt 1
          description: street 2 of the contact
        city:
          type: string
          example: Anytown
          description: city of the contact
        state:
          type: string
          example: NY
          description: state of the contact
        zipcode:
          type: string
          example: '04843'
          description: zipcode of the contact, supports zip5 and zip5+4
        birthday:
          type: string
          format: date
          example: "1985-04-15"
          description: optional birthday used by birthday automation workflows
        anniversary:
          type: string
          format: date
          example: "2015-09-20"
          description: optional anniversary used by anniversary automation workflows
        custom_1:
          type: string
          maxLength: 100
          description: optional custom field available as a merge tag
        custom_2:
          type: string
          maxLength: 100
        custom_3:
          type: string
          maxLength: 100
        custom_4:
          type: string
          maxLength: 100
        custom_5:
          type: string
          maxLength: 100
        custom_6:
          type: string
          maxLength: 100
        custom_7:
          type: string
          maxLength: 100
        custom_8:
          type: string
          maxLength: 100
        custom_9:
          type: string
          maxLength: 100
        custom_10:
          type: string
          maxLength: 100
      required:
      - first_name
      - last_name
      - street_1
      - city
      - state
      - zipcode
    sender_profiles:
      type: object
      properties:
        id:
          type: string
          example: "e307c2b1-3a28-49b5-b4d7-1139bed186f4"
          description: id of the sender profile (UUID)
        handwriting:
          type: string
          example: Atticus
          description: handwriting style of the sender
        full_name:
          type: string
          example: John Doe
          description: full name of the sender
        return_address:
          type: string
          example: 123 Main St, Anytown, NY 04843
          description: return address of the sender
    cards:
      type: object
      properties:
        id:
          type: string
          example: "84a450ad-00a6-4e41-811a-e3e409289a99"
          description: id of the card (UUID)
        name:
          type: string
          example: My Card
          description: name of the card
        orientation:
          type: string
          example: landscape
          description: orientation of the card
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: folded_greeting_card
          description: folded greeting card or jumbo postcard
        width:
          type: string
          example: '6.5'
          description: width of the card
        height:
          type: string
          example: '5.0'
          description: height of the card
        is_template:
          type: boolean
          example: false
          description: whether the card is a global template
        category:
          type: string
          example: holiday
          nullable: true
          description: template category when applicable
        qr_code_url:
          type: string
          example: https://google.com
          description: url of the qr code
        print_ready_url:
          type: string
          example: https://google.com
          description: url of the print ready file
        card_front_preview_url:
          type: string
          example: https://google.com
          description: url of the card front preview
        card_back_preview_url:
          type: string
          example: https://google.com
          description: url of the card back preview
    card_request_front:
      type: object
      required:
      - image_url
      properties:
        image_url:
          type: string
          example: "https://example.com/front.jpg"
        full_bleed:
          type: boolean
          example: true
        image_zoom:
          type: number
          format: float
          example: 1.0
    card_request_back:
      type: object
      description: For folded greeting cards, back may include image and QR fields. For jumbo_postcard cards, back.image_url, back.full_bleed, and back.image_zoom are rejected with 422; use only qr_code_url, qr_code_cta, and cta_font on the back.
      properties:
        image_url:
          type: string
          description: Folded greeting cards only. Rejected for jumbo_postcard cards.
          example: "https://example.com/back.jpg"
        full_bleed:
          type: boolean
          description: Folded greeting cards only. Rejected for jumbo_postcard cards.
          example: true
        image_zoom:
          type: number
          format: float
          description: Folded greeting cards only. Rejected for jumbo_postcard cards.
          example: 1.0
        qr_code_url:
          type: string
          example: "https://example.com/landing"
        qr_code_cta:
          type: string
          example: "Learn more"
        cta_font:
          type: string
          example: "Roboto"
    card_request:
      type: object
      description: Create an artwork-backed card. The legacy is_blank field is accepted as a no-op for older clients and ignored.
      required:
      - name
      - orientation
      - front
      properties:
        name:
          type: string
          example: "Spring Thank You"
        orientation:
          type: string
          enum:
          - landscape
          - portrait
          example: landscape
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: folded_greeting_card
          description: Use jumbo_postcard for 6 x 11 postcards. Jumbo postcards are always landscape and do not use envelope artwork.
        is_blank:
          type: boolean
          deprecated: true
          description: Legacy no-op accepted for backward compatibility. The value is ignored.
          example: false
        front:
          "$ref": "#/components/schemas/card_request_front"
        back:
          "$ref": "#/components/schemas/card_request_back"
    wrapped_card_request:
      type: object
      required:
      - card
      properties:
        card:
          "$ref": "#/components/schemas/card_request"
    card_create_response:
      type: object
      properties:
        id:
          type: string
          example: "card-123"
        user_id:
          type: string
          example: "user-123"
        name:
          type: string
          example: "Spring Thank You"
        category:
          type: string
          nullable: true
          example:
        orientation:
          type: string
          example: landscape
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: folded_greeting_card
        layout_type:
          type: string
          example: standard
        layout_version:
          type: integer
          example: 1
        width:
          type: number
          format: float
          example: 6.5
        width_bleed:
          type: number
          format: float
          example: 0.125
        height:
          type: number
          format: float
          example: 5.0
        height_bleed:
          type: number
          format: float
          example: 0.125
        is_blank:
          type: boolean
          deprecated: true
          description: Legacy field retained in responses for backward compatibility.
          example: false
        is_draft:
          type: boolean
          example: false
        is_global:
          type: boolean
          example: false
        pdf_url:
          type: string
          nullable: true
          example:
        created_at:
          type: string
          example: "2026-04-02T17:00:00Z"
        updated_at:
          type: string
          example: "2026-04-02T17:00:01Z"
    lists:
      type: object
      properties:
        id:
          type: string
          example: "be0e551b-9213-4127-af29-f7f07bb42f04"
          description: id of the list (UUID)
        name:
          type: string
          example: My List
          description: name of the list
        size:
          type: integer
          example: 100
          description: size of the list
        created_at:
          type: string
          example: '2021-01-01T00:00:00Z'
          description: date the list was created
        status:
          type: string
          example: completed
          description: processing status for the list import
        contacts_missing_custom_fields:
          type: integer
          example: 3
          description: number of contacts missing custom fields used in mail merges
    list_request:
      type: object
      required:
      - name
      - size
      - contacts
      properties:
        name:
          type: string
          example: "Top Prospects"
        size:
          type: integer
          example: 2
        contacts:
          type: array
          items:
            "$ref": "#/components/schemas/contact"
    wrapped_list_request:
      type: object
      required:
      - list
      properties:
        list:
          "$ref": "#/components/schemas/list_request"
    list_write_item:
      type: object
      properties:
        id:
          type: string
          example: "list-123"
        name:
          type: string
          example: "Top Prospects"
        size:
          type: integer
          example: 2
        status:
          type: string
          example: processing
        created_at:
          type: string
          example: "2026-04-02T18:00:00Z"
        contacts_accepted:
          type: integer
          example: 2
        contacts_rejected:
          type: integer
          example: 0
        rejected_contacts:
          type: array
          items:
            type: object
            additionalProperties: true
    list_write_response:
      type: object
      properties:
        list:
          "$ref": "#/components/schemas/list_write_item"
    list_detail_response:
      type: object
      properties:
        list:
          type: object
          properties:
            id:
              type: string
              example: "list-123"
            name:
              type: string
              example: "Top Prospects"
            size:
              type: integer
              example: 250
            status:
              type: string
              example: completed
            created_at:
              type: string
              example: "2026-04-01T15:00:00Z"
            updated_at:
              type: string
              example: "2026-04-01T15:30:00Z"
            contacts_accepted:
              type: integer
              example: 250
            contacts_rejected:
              type: integer
              example: 3
            rejected_contacts:
              type: array
              items:
                type: object
                additionalProperties: true
    messages:
      type: object
      properties:
        id:
          type: string
          example: "c4867882-edcd-45a1-be93-345172259e95"
          description: id of the message (UUID)
        name:
          type: string
          example: My Message
          description: name of the message
        body:
          type: string
          example: |-
            Dear {{greeting}},
             this is a test.
            Thanks,
             {{sender_first_name}}
          description: body of the message with merge tags or without
    api_message_response:
      type: object
      properties:
        id:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
        body:
          type: string
          example: |-
            Dear {{greeting}},

            Thanks for your time.

            {{sender_first_name}}
        created_at:
          type: string
          example: "2026-04-01T14:00:00Z"
          nullable: true
        updated_at:
          type: string
          example: "2026-04-01T14:05:00Z"
          nullable: true
        preview_requested_at:
          type: string
          example: "2026-04-01T14:06:00Z"
          nullable: true
        preview_url:
          type: string
          example: "https://live.simplynoted.com/previews/messages/123e4567-e89b-12d3-a456-426614174000.png"
          nullable: true
    message_validation_errors:
      type: object
      description: Validation errors keyed by request field.
      additionalProperties:
        type: array
        items:
          type: string
    pagination_metadata:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 100
        count:
          type: integer
          example: 2
        pages:
          type: integer
          example: 1
    mailing_request:
      type: object
      required:
      - name
      - card_id
      - message_id
      - sender_profile_id
      - list_ids
      properties:
        name:
          type: string
          example: "April Outreach"
        campaign_name:
          type: string
          example: "Q2 Pipeline"
          nullable: true
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: jumbo_postcard
          description: Physical mailing form factor. When omitted, the mailing uses the selected card's form_factor.
        card_id:
          type: string
          example: "card-123"
        message_id:
          type: string
          example: "message-123"
        sender_profile_id:
          type: string
          example: "sender-profile-123"
        list_ids:
          type: array
          description: List IDs to send to. Every ID must belong to the authenticated account and reference a completed list; unknown or inaccessible IDs return 422 with the rejected IDs in error.details.list_ids.
          items:
            type: string
            example: "list-123"
        schedule_type:
          type: string
          enum:
          - immediate
          - scheduled
          - birthday
          - anniversary
          example: scheduled
          description: Optional schedule mode; defaults to immediate. Use scheduled with send_date or target_date for one-time scheduled sends. Birthday and anniversary create automation workflows.
        send_date:
          type: string
          format: date
          example: "2026-04-15"
          description: Optional scheduled send date in YYYY-MM-DD format; aliases target_date. Required when schedule_type is scheduled. Impossible calendar dates, such as 2026-02-30, return 422 instead of being normalized.
        target_date:
          type: string
          format: date
          example: "2026-04-15"
          description: Backwards-compatible alias for send_date in YYYY-MM-DD format. Impossible calendar dates, such as 2026-02-30, return 422 instead of being normalized.
    wrapped_mailing_request:
      type: object
      required:
      - mailing
      properties:
        mailing:
          "$ref": "#/components/schemas/mailing_request"
    mailing_summary:
      type: object
      properties:
        id:
          type: string
          example: "mailing-123"
        name:
          type: string
          example: "April Outreach"
        campaign_name:
          type: string
          example: "Q2 Pipeline"
          nullable: true
        form_factor:
          type: string
          enum:
          - folded_greeting_card
          - jumbo_postcard
          example: jumbo_postcard
        size:
          type: integer
          example: 250
        created_at:
          type: string
          example: "2026-04-01T15:00:00Z"
        status:
          type: string
          example: Submitted
        submitted_at:
          type: string
          example: "2026-04-01 03:05 PM"
          nullable: true
        sent_at:
          type: string
          example: "2026-04-03 11:30 AM"
          nullable: true
        message_preview_url:
          type: string
          example: "https://live.simplynoted.com/previews/mailings/mailing-123-card.png"
          nullable: true
        envelope_preview_url:
          type: string
          example: "https://live.simplynoted.com/previews/mailings/mailing-123-envelope.png"
          nullable: true
        preview_requested_at:
          type: string
          example: "2026-04-01T15:02:00Z"
          nullable: true
        target_date:
          type: string
          example: "2026-04-05"
          nullable: true
        send_date:
          type: string
          example: "2026-04-05"
          nullable: true
        schedule_type:
          type: string
          example: scheduled
    mailing_detail:
      allOf:
      - "$ref": "#/components/schemas/mailing_summary"
      - type: object
        properties:
          card:
            "$ref": "#/components/schemas/cards"
          message:
            "$ref": "#/components/schemas/messages"
          lists:
            type: array
            items:
              "$ref": "#/components/schemas/lists"
          submission_errors:
            type: array
            items:
              type: string
          invalid_contacts_count:
            type: integer
            example: 2
    mailing_detail_response:
      type: object
      properties:
        mailing:
          "$ref": "#/components/schemas/mailing_detail"
    mailing_create_response:
      type: object
      properties:
        mailing:
          "$ref": "#/components/schemas/mailing_summary"
        token_balance:
          type: integer
          example: 245
        standard_token_balance:
          type: integer
          example: 245
        unlimited_token_balance:
          type: integer
          example: 1000
        postcard_token_balance:
          type: integer
          example: 80
        standard_postcard_token_balance:
          type: integer
          example: 80
        unlimited_postcard_token_balance:
          type: integer
          example: 900
        warnings:
          type: object
          properties:
            invalid_contacts_count:
              type: integer
              example: 2
            message:
              type: string
              example: "Some contacts were skipped due to validation errors"
    mailing_delete_response:
      type: object
      properties:
        mailing:
          type: object
          properties:
            id:
              type: string
              example: "mailing-123"
            status:
              type: string
              example: "Mailing was canceled and removed."
    api_error_response:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: validation_error
            message:
              type: string
              example: send_date must be a valid date
            details:
              type: object
              nullable: true
              additionalProperties: true
    mailing_tracking_summary:
      type: object
      properties:
        sent:
          type: integer
          example: 12
        in_transit:
          type: integer
          example: 8
        delivered:
          type: integer
          example: 230
        fail:
          type: integer
          example: 1
        total:
          type: integer
          example: 251
    mailing_tracking_contact:
      type: object
      properties:
        id:
          type: string
          example: "submission-contact-123"
        name:
          type: string
          example: "Avery Johnson"
          nullable: true
        address:
          type: string
          example: "123 Main St, Denver, CO 80205"
          nullable: true
        status:
          type: string
          example: delivered
          nullable: true
        expected_delivery_date:
          type: string
          example: "2026-04-05"
          nullable: true
        last_scan_date:
          type: string
          example: "2026-04-04"
          nullable: true
    mailing_tracking_response:
      type: object
      properties:
        summary:
          "$ref": "#/components/schemas/mailing_tracking_summary"
        contacts:
          type: array
          items:
            "$ref": "#/components/schemas/mailing_tracking_contact"
        pagination:
          "$ref": "#/components/schemas/pagination_metadata"
    recent_scan_event:
      type: object
      properties:
        id:
          type: string
          example: "evt-newest"
        created_at:
          type: string
          example: "2026-04-02T12:00:00Z"
        ip_address:
          type: string
          example: "203.0.113.10"
          nullable: true
    recent_scan_person:
      type: object
      properties:
        first_name:
          type: string
          example: "Avery"
          nullable: true
        last_name:
          type: string
          example: "Johnson"
          nullable: true
        email:
          type: string
          example: "avery@example.com"
          nullable: true
        phone:
          type: string
          example: "555-555-0123"
          nullable: true
        custom_1:
          type: string
          example: "Prospect"
          nullable: true
        custom_2:
          type: string
          nullable: true
        custom_3:
          type: string
          nullable: true
        custom_4:
          type: string
          nullable: true
        custom_5:
          type: string
          nullable: true
        custom_6:
          type: string
          nullable: true
        custom_7:
          type: string
          nullable: true
        custom_8:
          type: string
          nullable: true
        custom_9:
          type: string
          nullable: true
        custom_10:
          type: string
          nullable: true
    recent_scan_barcode:
      type: object
      properties:
        code:
          type: string
          example: "scan-newest"
        mailing_id:
          type: string
          example: "mailing-123"
        list_contact_id:
          type: string
          example: "list-contact-123"
        redirect_url:
          type: string
          example: "https://example.test/newest"
          nullable: true
        created_at:
          type: string
          example: "2026-04-01T10:00:00Z"
          nullable: true
        mailing_name:
          type: string
          example: "April Outreach"
          nullable: true
        person:
          "$ref": "#/components/schemas/recent_scan_person"
        events:
          type: array
          items:
            "$ref": "#/components/schemas/recent_scan_event"
    recent_scan_item:
      type: object
      properties:
        barcodes:
          "$ref": "#/components/schemas/recent_scan_barcode"
    sender_profile_request:
      type: object
      required:
      - first_name
      - last_name
      - handwriting_style_id
      - street_1
      - city
      - state_code
      - zipcode
      properties:
        first_name:
          type: string
          example: "John"
          description: First name of the sender
        last_name:
          type: string
          example: "Doe"
          description: Last name of the sender
        handwriting_style_id:
          type: integer
          example: 1
          description: ID of the handwriting style to use
        street_1:
          type: string
          example: "123 Main St"
          description: Primary street address
        street_2:
          type: string
          example: "Apt 4B"
          description: Secondary street address (optional)
        city:
          type: string
          example: "Anytown"
          description: City name
        state_code:
          type: string
          example: "NY"
          description: Two-letter state code
        zipcode:
          type: string
          example: "12345"
          description: 5 or 9 digit zip code
        email:
          type: string
          example: "john@example.com"
          description: Email address (optional)
        phone:
          type: string
          example: "555-123-4567"
          description: Phone number (optional)
    wrapped_sender_profile_request:
      type: object
      required:
      - sender_profile
      properties:
        sender_profile:
          "$ref": "#/components/schemas/sender_profile_request"
    sender_profile_response:
      type: object
      properties:
        id:
          type: string
          example: "123e4567-e89b-12d3-a456-426614174000"
          description: Unique identifier for the sender profile
        handwriting_style_id:
          type: integer
          example: 1
          description: ID of the handwriting style used
        handwriting_style:
          type: string
          example: "Atticus"
          description: Name of the handwriting style
        first_name:
          type: string
          example: "John"
          description: First name of the sender
        last_name:
          type: string
          example: "Doe"
          description: Last name of the sender
        return_address:
          type: string
          example: "123 Main St, Anytown, NY 12345"
          description: Full formatted return address
        phone:
          type: string
          example: "555-123-4567"
          description: Phone number if provided
        email:
          type: string
          example: "john@example.com"
          description: Email address if provided
        archived_at:
          type: string
          format: date-time
          nullable: true
          example: null
          description: Archive timestamp; archived profiles are omitted from profile and asset lists
    handwriting_style:
      type: object
      properties:
        id:
          type: integer
          example: 1
          description: Unique identifier for the handwriting style
        name:
          type: string
          example: "Atticus"
          description: Display name of the handwriting style
          enum:
            - Atticus
            - Hoffman
            - London
            - Madison
            - Finch
            - Ophelia
            - Riviera
            - Tangerine
            - Woodson
    webhook:
      type: object
      description: A webhook subscription owned by the authenticated account.
      properties:
        id:
          type: string
          format: uuid
          example: "1c01ea72-25df-4b4d-8ae6-cc3704dbdd3f"
        target_url:
          type: string
          format: uri
          example: https://example.com/webhooks/simplynoted
          description: HTTPS URL that will receive event POST requests.
        description:
          type: string
          nullable: true
          example: Production delivery hook
        event_types:
          type: array
          items:
            type: string
            enum:
            - delivery
            - qr_scan
          example:
          - delivery
          - qr_scan
        status:
          type: string
          enum:
          - active
          - paused
          - disabled_by_failures
          example: active
        signing_enabled:
          type: boolean
          example: false
          description: True when an HMAC signing secret is configured for this webhook.
        created_at:
          type: string
          format: date-time
          example: '2026-04-01T12:00:00Z'
        last_delivered_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-04-07T09:15:22Z'
        last_failed_at:
          type: string
          format: date-time
          nullable: true
          example: null
        consecutive_failures:
          type: integer
          example: 0
          description: Number of consecutive delivery failures. A webhook is auto-disabled after 10.
    webhook_request:
      type: object
      required:
      - target_url
      - event_types
      properties:
        target_url:
          type: string
          format: uri
          example: https://example.com/webhooks/simplynoted
          description: Must be an `https://` URL. Must be unique within the account.
        description:
          type: string
          example: Production delivery hook
          description: Optional human-readable label shown in the dashboard.
        event_types:
          type: array
          items:
            type: string
            enum:
            - delivery
            - qr_scan
          example:
          - delivery
          - qr_scan
    webhook_update_request:
      type: object
      properties:
        target_url:
          type: string
          format: uri
          example: https://example.com/webhooks/simplynoted
          description: Must be an `https://` URL. Must be unique within the account.
        description:
          type: string
          example: Production delivery hook
          description: Optional human-readable label shown in the dashboard.
        event_types:
          type: array
          items:
            type: string
            enum:
            - delivery
            - qr_scan
          example:
          - delivery
          - qr_scan
  examples:
    token_balance_response:
      summary: Current token balance
      value:
        token_balance: 245
        standard_token_balance: 245
        unlimited_token_balance: 1000
        postcard_token_balance: 80
        standard_postcard_token_balance: 80
        unlimited_postcard_token_balance: 900
    assets_response:
      summary: Reusable assets and pagination metadata
      value:
        assets:
          sender_profiles:
            - id: "sender-profile-123"
              handwriting: "Atticus"
              full_name: "Jordan Smith"
              return_address: "123 Main St, Denver, CO 80205"
          cards:
            - id: "card-123"
              name: "Spring Thank You"
              orientation: "landscape"
              width: "6.5"
              height: "5.0"
              qr_code_url: "https://cdn.simplynoted.com/cards/card-123/qr.png"
              print_ready_url: "https://cdn.simplynoted.com/cards/card-123/print.pdf"
              card_front_preview_url: "https://cdn.simplynoted.com/cards/card-123/front.png"
              card_back_preview_url: "https://cdn.simplynoted.com/cards/card-123/back.png"
          lists:
            - id: "list-123"
              name: "Top Prospects"
              size: 250
              created_at: "2026-04-01T15:00:00Z"
              status: "completed"
              contacts_missing_custom_fields: 3
          messages:
            - id: "message-123"
              name: "Warm Follow-up"
              body: |-
                Dear {{greeting}},

                Thanks for your time.

                {{sender_first_name}}
        pagination:
          sender_profiles:
            page: 1
            limit: 100
            count: 1
            pages: 1
          cards:
            page: 1
            limit: 100
            count: 1
            pages: 1
          lists:
            page: 1
            limit: 100
            count: 1
            pages: 1
          messages:
            page: 1
            limit: 100
            count: 1
            pages: 1
    recent_scans_response:
      summary: Paginated recent scans across all mailings
      value:
        recent_scans:
          - barcodes:
              code: "scan-newest"
              mailing_id: "mailing-456"
              list_contact_id: "list-contact-789"
              redirect_url: "https://example.test/newest"
              created_at: "2026-04-01T10:00:00Z"
              mailing_name: "April Outreach"
              person:
                first_name: "Avery"
                last_name: "Johnson"
                email: "avery@example.com"
                phone: "555-555-0123"
                custom_1: "Prospect"
              events:
                - id: "evt-newest"
                  created_at: "2026-04-02T12:00:00Z"
                  ip_address: "203.0.113.10"
          - barcodes:
              code: "scan-older"
              mailing_id: "mailing-123"
              list_contact_id: "list-contact-456"
              redirect_url: "https://example.test/older"
              created_at: "2026-04-01T09:00:00Z"
              mailing_name: "March Follow-up"
              person:
                first_name: "Taylor"
                last_name: "Lee"
                email: "taylor@example.com"
                phone: "555-555-0199"
                custom_1: "VIP"
              events:
                - id: "evt-older"
                  created_at: "2026-04-02T09:30:00Z"
                  ip_address: "203.0.113.11"
        pagination:
          page: 1
          limit: 100
          count: 2
          pages: 1
    mailing_recent_scans_response:
      summary: Recent scans for a single mailing
      value:
        recent_scans:
          - barcodes:
              code: "scan-mailing-1"
              mailing_id: "mailing-123"
              list_contact_id: "list-contact-456"
              redirect_url: "https://example.test/mailing-123"
              created_at: "2026-04-01T09:00:00Z"
              mailing_name: "March Follow-up"
              person:
                first_name: "Taylor"
                last_name: "Lee"
                email: "taylor@example.com"
                phone: "555-555-0199"
                custom_1: "VIP"
              events:
                - id: "evt-mailing-1"
                  created_at: "2026-04-02T09:30:00Z"
                  ip_address: "203.0.113.11"
    messages_response:
      summary: Saved message templates
      value:
        messages:
          - id: "message-123"
            body: |-
              Dear {{greeting}},

              Thanks for your time.

              {{sender_first_name}}
            created_at: "2026-04-01T14:00:00Z"
            updated_at: "2026-04-01T14:05:00Z"
            preview_requested_at: "2026-04-01T14:06:00Z"
            preview_url: "https://live.simplynoted.com/previews/messages/message-123.png"
        pagination:
          page: 1
          limit: 500
          count: 1
          pages: 1
    message_response:
      summary: Single saved message
      value:
        id: "message-123"
        body: |-
          Dear {{greeting}},

          Thanks for your time.

          {{sender_first_name}}
        created_at: "2026-04-01T14:00:00Z"
        updated_at: "2026-04-01T14:05:00Z"
        preview_requested_at: "2026-04-01T14:06:00Z"
        preview_url: "https://live.simplynoted.com/previews/messages/message-123.png"
    message_validation_errors:
      summary: Message body exceeds the character limit
      value:
        body:
        - must be 500 non-whitespace characters or less
    sender_profiles_response:
      summary: Sender profiles with pagination metadata
      value:
        sender_profiles:
          - id: "123e4567-e89b-12d3-a456-426614174000"
            handwriting_style_id: 1
            handwriting_style: "Atticus"
            first_name: "Jordan"
            last_name: "Smith"
            return_address: "123 Main St, Denver, CO 80205"
            phone: "555-123-4567"
            email: "jordan@example.com"
            archived_at: null
        pagination:
          page: 1
          limit: 500
          count: 1
          pages: 1
    sender_profile_response:
      summary: Single sender profile
      value:
        sender_profile:
          id: "123e4567-e89b-12d3-a456-426614174000"
          handwriting_style_id: 1
          handwriting_style: "Atticus"
          first_name: "Jordan"
          last_name: "Smith"
          return_address: "123 Main St, Denver, CO 80205"
          phone: "555-123-4567"
          email: "jordan@example.com"
          archived_at: null
    sender_profile_created_response:
      summary: Created sender profile
      value:
        message: "Sender profile created successfully"
        sender_profile:
          id: "123e4567-e89b-12d3-a456-426614174000"
          handwriting_style_id: 1
          handwriting_style: "Atticus"
          first_name: "Jordan"
          last_name: "Smith"
          return_address: "123 Main St, Denver, CO 80205"
          phone: "555-123-4567"
          email: "jordan@example.com"
          archived_at: null
    sender_profile_updated_response:
      summary: Updated sender profile
      value:
        message: "Sender profile updated successfully"
        sender_profile:
          id: "123e4567-e89b-12d3-a456-426614174000"
          handwriting_style_id: 1
          handwriting_style: "Atticus"
          first_name: "Jordan"
          last_name: "Smith"
          return_address: "456 Elm St, Denver, CO 80206"
          phone: "555-123-4567"
          email: "jordan@example.com"
          archived_at: null
    sender_profile_archived_response:
      summary: Archived sender profile
      value:
        message: "Sender profile archived successfully"
    handwriting_styles_response:
      summary: Available handwriting styles
      value:
        handwriting_styles:
          - id: 1
            name: "Atticus"
          - id: 2
            name: "Finch"
          - id: 3
            name: "Riviera"
        pagination:
          page: 1
          limit: 500
          count: 3
          pages: 1
    lists_response:
      summary: Recipient lists with pagination metadata
      value:
        lists:
          - id: "list-123"
            name: "Top Prospects"
            size: 250
            created_at: "2026-04-01T15:00:00Z"
            status: "completed"
            contacts_missing_custom_fields: 3
        pagination:
          page: 1
          limit: 500
          count: 1
          pages: 1
    list_create_request:
      summary: Create a recipient list
      value:
        list:
          name: "Top Prospects"
          size: 2
          contacts:
            - first_name: "Avery"
              last_name: "Johnson"
              email: "avery@example.com"
              phone: "555-555-0123"
              street_1: "123 Main St"
              city: "Denver"
              state: "CO"
              zipcode: "80205"
              custom_1: "Prospect"
            - first_name: "Taylor"
              last_name: "Lee"
              email: "taylor@example.com"
              phone: "555-555-0199"
              street_1: "456 Oak Ave"
              city: "Austin"
              state: "TX"
              zipcode: "78701"
              custom_1: "VIP"
    list_created_response:
      summary: Accepted list import
      value:
        list:
          id: "list-123"
          name: "Top Prospects"
          size: 2
          status: "processing"
          created_at: "2026-04-02T18:00:00Z"
          contacts_accepted: 2
          contacts_rejected: 0
    list_response:
      summary: Single recipient list
      value:
        list:
          id: "list-123"
          name: "Top Prospects"
          size: 250
          status: "completed"
          created_at: "2026-04-01T15:00:00Z"
          updated_at: "2026-04-01T15:05:00Z"
          contacts_accepted: 250
          contacts_rejected: 0
    cards_response:
      summary: Cards with pagination metadata
      value:
        cards:
          - id: "card-123"
            name: "Spring Thank You"
            orientation: "landscape"
            form_factor: "folded_greeting_card"
            width: "6.5"
            height: "5.0"
            is_template: false
            category:
            qr_code_url: "https://example.test/landing"
            print_ready_url: "https://cdn.simplynoted.com/cards/card-123/print.pdf"
            card_front_preview_url: "https://cdn.simplynoted.com/cards/card-123/front.png"
            card_back_preview_url: "https://cdn.simplynoted.com/cards/card-123/back.png"
        pagination:
          page: 1
          limit: 500
          count: 1
          pages: 1
    card_create_request:
      summary: Create a new card
      value:
        card:
          name: "Spring Thank You"
          orientation: "landscape"
          form_factor: "folded_greeting_card"
          front:
            image_url: "https://images.example.com/cards/front.jpg"
            full_bleed: true
            image_zoom: 1.0
          back:
            image_url: "https://images.example.com/cards/back.jpg"
            full_bleed: true
            image_zoom: 1.0
            qr_code_url: "https://example.test/landing"
            qr_code_cta: "Learn more"
            cta_font: "Roboto"
    card_created_response:
      summary: Created card record
      value:
        id: "card-123"
        user_id: "user-123"
        name: "Spring Thank You"
        category:
        orientation: "landscape"
        form_factor: "folded_greeting_card"
        layout_type: "standard"
        layout_version: 1
        width: 6.5
        width_bleed: 0.125
        height: 5.0
        height_bleed: 0.125
        is_blank: false
        is_draft: false
        is_global: false
        pdf_url:
        created_at: "2026-04-02T17:00:00Z"
        updated_at: "2026-04-02T17:00:01Z"
    card_response:
      summary: Single card summary
      value:
        id: "card-123"
        name: "Spring Thank You"
        orientation: "landscape"
        form_factor: "folded_greeting_card"
        width: "6.5"
        height: "5.0"
        is_template: false
        category:
        qr_code_url: "https://example.test/landing"
        print_ready_url: "https://cdn.simplynoted.com/cards/card-123/print.pdf"
        card_front_preview_url: "https://cdn.simplynoted.com/cards/card-123/front.png"
        card_back_preview_url: "https://cdn.simplynoted.com/cards/card-123/back.png"
    mailings_response:
      summary: Mailings with pagination metadata
      value:
        mailings:
          - id: "mailing-123"
            name: "April Outreach"
            campaign_name: "Q2 Pipeline"
            form_factor: "jumbo_postcard"
            size: 250
            created_at: "2026-04-01T15:00:00Z"
            status: "Submitted"
            submitted_at: "2026-04-01 03:05 PM"
            sent_at: "2026-04-03 11:30 AM"
            message_preview_url: "https://live.simplynoted.com/previews/mailings/mailing-123-card.png"
            envelope_preview_url:
            preview_requested_at: "2026-04-01T15:02:00Z"
            target_date: "2026-04-05"
            send_date: "2026-04-05"
            schedule_type: "scheduled"
        pagination:
          page: 1
          limit: 100
          count: 1
          pages: 1
    mailing_created_response:
      summary: Created mailing
      value:
        mailing:
          id: "mailing-123"
          name: "April Outreach"
          campaign_name: "Q2 Pipeline"
          form_factor: "jumbo_postcard"
          size: 250
          created_at: "2026-04-01T15:00:00Z"
          status: "Submitted"
          submitted_at: "2026-04-01 03:05 PM"
          sent_at:
          message_preview_url: "https://live.simplynoted.com/previews/mailings/mailing-123-card.png"
          envelope_preview_url:
          preview_requested_at: "2026-04-01T15:02:00Z"
          target_date: "2026-04-05"
          send_date: "2026-04-05"
          schedule_type: "scheduled"
        token_balance: 245
        standard_token_balance: 245
        unlimited_token_balance: 1000
        postcard_token_balance: 80
        standard_postcard_token_balance: 80
        unlimited_postcard_token_balance: 900
        warnings:
          invalid_contacts_count: 2
          message: "Some contacts were skipped due to validation errors"
    mailing_invalid_send_date_response:
      summary: Invalid scheduled send date
      value:
        error:
          code: validation_error
          message: send_date must be a valid date
    mailing_inaccessible_list_response:
      summary: Unknown or inaccessible list IDs
      value:
        error:
          code: validation_error
          message: One or more lists could not be found
          details:
            list_ids:
            - "list-from-another-account"
    mailing_response:
      summary: Single mailing details
      value:
        mailing:
          id: "mailing-123"
          name: "April Outreach"
          campaign_name: "Q2 Pipeline"
          form_factor: "jumbo_postcard"
          size: 250
          created_at: "2026-04-01T15:00:00Z"
          status: "Submitted"
          submitted_at: "2026-04-01 03:05 PM"
          sent_at: "2026-04-03 11:30 AM"
          message_preview_url: "https://live.simplynoted.com/previews/mailings/mailing-123-card.png"
          envelope_preview_url:
          preview_requested_at: "2026-04-01T15:02:00Z"
          target_date: "2026-04-05"
          send_date: "2026-04-05"
          schedule_type: "scheduled"
          card:
            id: "card-123"
            name: "Spring Thank You"
            orientation: "landscape"
            form_factor: "jumbo_postcard"
            width: "11.0"
            height: "6.0"
            is_template: false
            category:
            qr_code_url: "https://example.test/landing"
            print_ready_url: "https://cdn.simplynoted.com/cards/card-123/print.pdf"
            card_front_preview_url: "https://cdn.simplynoted.com/cards/card-123/front.png"
            card_back_preview_url: "https://cdn.simplynoted.com/cards/card-123/back.png"
          message:
            id: "message-123"
            name: "Warm Follow-up"
            body: |-
              Dear {{greeting}},

              Thanks for your time.

              {{sender_first_name}}
          lists:
            - id: "list-123"
              name: "Top Prospects"
              size: 250
              created_at: "2026-04-01T15:00:00Z"
              status: "completed"
              contacts_missing_custom_fields: 3
          submission_errors:
            - "Address normalization failed for 1 contact"
          invalid_contacts_count: 1
    mailing_deleted_response:
      summary: Deleted mailing
      value:
        mailing:
          id: "mailing-123"
          status: "Mailing was canceled and removed."
    mailing_tracking_response:
      summary: Mailing tracking summary and contacts
      value:
        summary:
          sent: 12
          in_transit: 8
          delivered: 230
          fail: 1
          total: 251
        contacts:
          - id: "submission-contact-123"
            name: "Avery Johnson"
            address: "123 Main St, Denver, CO 80205"
            status: "delivered"
            expected_delivery_date: "2026-04-05"
            last_scan_date: "2026-04-04"
          - id: "submission-contact-124"
            name: "Taylor Lee"
            address: "456 Oak Ave, Austin, TX 78701"
            status: "in_transit"
            expected_delivery_date: "2026-04-06"
            last_scan_date: "2026-04-03"
        pagination:
          page: 1
          limit: 25
          count: 2
          pages: 1
    message_deleted_response:
      summary: Deleted message
      value:
        message: "Message was successfully destroyed."
    single_card_mailing_response:
      summary: Created single card mailing
      value:
        card_id: "card-123"
        message_id: "message-123"
        sender_profile_id: "sender-profile-123"
        name: "Spring Check-in"
        form_factor: "jumbo_postcard"
        contact:
          first_name: "Avery"
          last_name: "Johnson"
          email: "avery@example.com"
          phone: "555-555-0123"
          street_1: "123 Main St"
          city: "Denver"
          state: "CO"
          zipcode: "80205"
          custom_1: "Prospect"
        user_id: "user-123"
        mailing_id: "mailing-123"
