Sendoso Smart Send API

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.
  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
    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'
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
  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