Sendoso Sends API

openapi: 3.2.0
info:
  title: Sendoso Core Sends API
  version: '3'
  summary: Automate physical gift, direct mail and eGift sending, and read campaigns, users and teams.
  description: The Sendoso Core API (v3) lets you programmatically trigger sends, embed sending into your own forms, and read the campaigns ("touches"), users and team groups behind them.
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-on: '2026-08-13'
  x-source-docs: https://developer.sendoso.com/llms.txt
servers:
- url: https://app.sendoso.com
  description: Production
- url: https://app.staging.sendo.so
  description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
security:
- OAuth2: []
tags:
- name: Sends
  description: Create and retrieve gift, direct mail and eGift sends.
paths:
  /api/v3/send:
    get:
      operationId: getSends
      summary: Retrieve All Sends
      description: Retrieves a list of all sends initiated by anyone in the organization.
      tags:
      - Sends
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/sends/get-sends
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A page of sends.
          content:
            application/json:
              schema:
                type: object
                required:
                - current_page
                - per_page
                - total_count
                - sends
                properties:
                  current_page:
                    type: integer
                  per_page:
                    type: integer
                  total_count:
                    type: integer
                  sends:
                    type: array
                    items:
                      $ref: '#/components/schemas/Send'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createSend
      summary: Create a Send
      description: 'Create a send. Sendoso documents three request shapes against this single path and method, distinguished by the `via` discriminator and the address fields: a physical gift to a known address, a physical gift with address collection, and an eGift sent via Sendoso email. Sendoso does NOT deduplicate payloads — an identical request sent twice creates two sends.'
      tags:
      - Sends
      externalDocs:
        description: Send Physical Gift
        url: https://developer.sendoso.com/rest-api/reference/sends/physical/physical
      x-documented-variants:
      - title: Send Physical Gift
        url: https://developer.sendoso.com/rest-api/reference/sends/physical/physical
      - title: Send Physical Gift with Address Collection
        url: https://developer.sendoso.com/rest-api/reference/sends/physical/physicalAC
      - title: Send eGift via Sendoso Email
        url: https://developer.sendoso.com/rest-api/reference/sends/egift/eGift
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - send
              properties:
                send:
                  oneOf:
                  - $ref: '#/components/schemas/PhysicalSendRequest'
                  - $ref: '#/components/schemas/PhysicalSendAddressCollectionRequest'
                  - $ref: '#/components/schemas/EgiftSendRequest'
      responses:
        '200':
          description: Send created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResult'
        '400':
          description: 'Bad request. Documented message example: "email can''t be blank".'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 'Campaign not found. Documented message: "Touch not found".'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v3/send/generate_egift_links:
    post:
      operationId: generateEgiftLinks
      summary: Generate eGift Links
      description: Generate one or more eGift links to embed in your own outreach to the recipient(s). Each recipient gets a unique link associated to the email passed in the request.
      tags:
      - Sends
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/sends/egift/eGiftlink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - send
              properties:
                send:
                  type: object
                  required:
                  - touch_id
                  - via
                  - via_from
                  - recipient_users
                  properties:
                    touch_id:
                      type: integer
                      description: The ID of the campaign within Sendoso you want to send.
                    via:
                      type: string
                      const: generate_egift_links
                    via_from:
                      type: string
                      description: The name of the application making the send request. Keep this consistent per application.
                    recipient_users:
                      type: array
                      description: An array of recipient emails to generate links for.
                      items:
                        type: object
                        required:
                        - email
                        properties:
                          email:
                            type: string
      responses:
        '200':
          description: Links generated.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - message
                - egift_links
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  egift_links:
                    type: array
                    items:
                      type: object
                      required:
                      - egift_link
                      - recipient_email_or_phone_number
                      properties:
                        egift_link:
                          type: string
                          description: The link generated for this specific recipient.
                        recipient_email_or_phone_number:
                          type: string
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 'Campaign not found. Documented message: "Touch not found".'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Documented message: "The access token is invalid".'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests. Sendoso throttles application clients sending more than 10 requests/second; the client is temporarily blocked from making further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PhysicalSendAddressCollectionRequest:
      title: Send Physical Gift with Address Collection
      type: object
      description: Send a physical item when the recipient address is unknown.
      required:
      - touch_id
      - name
      - email
      - no_address
      - confirm_address
      - address_confirmation_via
      - resume_with_unconfirmed_address
      - expire_after_days
      - hide_product_info
      - via
      - via_from
      properties:
        touch_id:
          type: integer
        name:
          type: string
        email:
          type: string
        custom_message:
          type: string
        no_address:
          type: boolean
          const: true
        confirm_address:
          type: boolean
          const: true
        address_confirmation_via:
          type: string
          enum:
          - email
          - link
          description: '`email` sends the recipient an email; `link` returns a link in the response and also mails a link to the sender.'
        resume_with_unconfirmed_address:
          type: boolean
          description: Sendoso documents leaving this FALSE for this endpoint.
        expire_after_days:
          type: integer
          minimum: 2
          maximum: 7
          description: How many days the address collection form stays valid.
        hide_product_info:
          type: boolean
          description: Whether the gift name and image appear on the address collection page.
        address_confirmation_custom_message:
          type: string
          description: Only applicable when sending address collection via the email method.
        via:
          type: string
          const: single_person_or_company
        via_from:
          type: string
    Send:
      type: object
      required:
      - id
      - send_gid
      - type
      - subtype
      - currency
      - current_total_cost
      properties:
        id:
          type: integer
        send_gid:
          type: string
          description: The gid of the send.
        type:
          type: string
          description: 'The send''s type. Documented values: Amazon, Handwritten Notes, Inventoried Sends, Sendoso Choice, Sendoso Direct, eGifts International, eGifts USA.'
        subtype:
          type: string
          description: The send's subtype. Documented values include Bundles, Buy/Send via Amazon, Coffee, Custom, Donate to Charity, Experiences, Handwritten Notes, Lunch, On-Demand, Wine, and the per-country eGift Cards variants.
        currency:
          type: string
          description: ISO 4217.
        current_total_cost:
          type: string
          description: The send's cost at the time of the request. May change until the send reaches a final status.
    EgiftSendRequest:
      title: Send eGift via Sendoso Email
      type: object
      description: Send an eGift directly to a recipient.
      required:
      - touch_id
      - email
      - via
      - via_from
      properties:
        touch_id:
          type: integer
        name:
          type: string
        email:
          type: string
        custom_message:
          type: string
          description: The message that goes in the body of the eGift email.
        via:
          type: string
          const: single_email_address
        via_from:
          type: string
    PhysicalSendRequest:
      title: Send Physical Gift
      type: object
      description: Send a physical item directly to a recipient when their address is known.
      required:
      - touch_id
      - name
      - email
      - address
      - city
      - state
      - zip
      - country
      - confirm_address
      - via
      - via_from
      properties:
        touch_id:
          type: integer
        name:
          type: string
        email:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
        country:
          type: string
        mobile_no:
          type: number
          description: Required for non-US addresses — a request without it will fail for any non-US address.
        custom_message:
          type: string
          description: The message that goes on the notecard in the gift box, if applicable.
        confirm_address:
          type: boolean
          description: Send `false` when you are providing the recipient address.
        via:
          type: string
          const: single_person_or_company
        via_from:
          type: string
    Error:
      type: object
      description: Sendoso's error envelope. Not RFC 9457 problem+json — errors are returned as `application/json` with a `success` flag and a human-readable `message`. Some documented 401 bodies use `description` and `expired` instead of `message`.
      properties:
        success:
          type: boolean
        message:
          type: string
        description:
          type: string
        expired:
          type: boolean
    SendResult:
      type: object
      required:
      - success
      - message
      - tracking_code
      properties:
        success:
          type: boolean
          description: Always `true` for 2xx responses.
        message:
          type: string
        tracking_code:
          type: string
          description: The send's unique tracking code.
        tracking_url:
          type: string
          description: The send's unique tracking URL. Returned for eGift sends.
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: The page number of the results you want to retrieve. The first page is 1.
      schema:
        type: integer
        minimum: 1
    PerPage:
      name: per_page
      in: query
      required: false
      description: The number of results to be returned per page. Max is 100.
      schema:
        type: integer
        maximum: 100
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 Authorization Code grant. Register your application by contacting developers@sendoso.com to receive a client ID and client secret. Access tokens live 7200 seconds (2 hours) and are refreshed at the same token endpoint. Tokens are sent as `Authorization: Bearer <token>`.'
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendoso.com/oauth/authorize
          tokenUrl: https://app.sendoso.com/oauth/token
          refreshUrl: https://app.sendoso.com/oauth/token
          scopes:
            public: Access the user's basic information.
            write: Send gifts on the user's behalf.
            update: Update the user's account details.
            marketplace: Access the marketplace API.
            smartsend: Access the smartsend API.
externalDocs:
  description: Sendoso REST API documentation
  url: https://developer.sendoso.com/rest-api/overview/introduction