openapi: 3.2.0
info:
  title: Sendoso Marketplace Smart Send API
  version: '3'
  summary: Browse the Sendoso marketplace catalog, get AI gift recommendations, and send either.
  description: 'The Sendoso Marketplace and SmartSend API lets you send physical gifts and direct mail from Sendoso''s catalog rather than from a pre-configured campaign. SmartSend picks the gift for you based on the recipient''s interests and preferences.


    Sendoso does not publish an OpenAPI document. This description was generated by API Evangelist from Sendoso''s own published reference pages at https://developer.sendoso.com — every path, method, parameter and response field below is traceable to the page named in that operation''s `externalDocs`.'
  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/marketplace/overview/introduction
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: SmartSend
  description: AI-selected gift recommendations and sending them.
paths:
  /api/v3/smartsend/recommendations:
    get:
      operationId: getGiftRecommendations
      summary: Get Gift Recommendations
      description: Retrieves a list of recommendations for a given recipient email.
      tags:
      - SmartSend
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/recommendations/get-recommendations
      security:
      - OAuth2:
        - smartsend
      parameters:
      - name: recipient_email
        in: query
        required: true
        description: The email of the recipient.
        schema:
          type: string
      - name: price_lte_usd
        in: query
        required: false
        description: The maximum price of products in USD.
        schema:
          type: integer
      - name: ship_to_country_code
        in: query
        required: false
        description: The country code to ship to.
        schema:
          type: string
      responses:
        '200':
          description: Recommended products.
          content:
            application/json:
              schema:
                type: object
                required:
                - products
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecommendedProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v3/smartsend/recommendations/send:
    post:
      operationId: sendRecommendation
      summary: Send a Recommendation
      description: Automatically pick and send a recommendation to a recipient.
      tags:
      - SmartSend
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/recommendations/send
      security:
      - OAuth2:
        - smartsend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - recipient_email
              - recipient_first_name
              - recipient_last_name
              properties:
                recipient_email:
                  type: string
                recipient_first_name:
                  type: string
                recipient_last_name:
                  type: string
                price_lte_usd:
                  type: integer
                  description: Limit the maximum price of the product in USD.
                ship_to_country_code:
                  type: string
                message:
                  type: string
                gift_exchange_enabled:
                  type: boolean
                meeting_url:
                  type: string
                require_approval:
                  type: boolean
      responses:
        '200':
          description: Send created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceSendResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests. The Marketplace and SmartSend APIs are limited to 100 requests per minute per user and return an `X-Rate-Limit-Reset` header indicating when the limit resets.
      headers:
        X-Rate-Limit-Reset:
          description: The time at which the rate limit will reset.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Variant:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        estimated_total_price:
          type: object
          required:
          - currency
          - price_per_unit
          properties:
            currency:
              type: string
            price_per_unit:
              type: string
        images:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    MarketplaceSendResult:
      type: object
      required:
      - products
      - send
      properties:
        products:
          type: array
          items:
            type: object
            required:
            - variant_id
            properties:
              variant_id:
                type: string
        send:
          type: object
          required:
          - id
          properties:
            id:
              type: string
    RecommendedProduct:
      type: object
      required:
      - id
      - name
      - description
      - interests
      - variants
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        interests:
          type: array
          description: The interests the product was recommended on.
          items:
            type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code grant, same authorization server as the Core API. Marketplace operations require the `marketplace` scope; SmartSend operations require `smartsend`.
      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 Marketplace / SmartSend documentation
  url: https://developer.sendoso.com/marketplace/overview/introduction