Nooks Emails API

openapi: 3.2.0
info:
  title: Nooks Sequencing Emails API
  version: 0.1.0
  description: The Nooks Sequencing API provides programmatic access to manage sequences, tasks, templates, and prospect engagement workflows created using the Nooks SEP.
  contact:
    name: Nooks API Support
    email: support@nooks.in
    url: https://www.nooks.in
  license:
    name: Proprietary
  x-logo:
    url: ./nooks-logo.svg
    altText: Nooks Logo
    href: https://www.nooks.ai
servers:
- url: https://partner-api.nooks.in/v1
  description: Production API
security:
- BearerAuth: []
tags:
- name: Emails
  description: Access email records
paths:
  /emails:
    get:
      operationId: listEmails
      summary: List emails
      description: 'Returns a paginated list of emails. Supports filtering by ID, prospect, task, status, and updatedAt range.


        Example:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?page[size]=50'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by prospect:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?filter[prospect][id]=770e8400-e29b-41d4-a716-446655440003'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by task (the sequence task that triggered the email):

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?filter[task][id]=990e8400-e29b-41d4-a716-446655440099'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by account (joins through the email''s prospect):

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?filter[account][id]=990e8400-e29b-41d4-a716-446655440099'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by delivery status:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?filter[status]=sent,failed'' \

        -H "Authorization: Bearer nooks-api-..."

        ```


        Filter by updatedAt range:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails?filter[updatedAt][gte]=2025-01-01T00:00:00Z'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Emails
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageAfter'
      - $ref: '#/components/parameters/PageBefore'
      - $ref: '#/components/parameters/FilterId'
      - name: filter[prospect][id]
        in: query
        description: Filter emails for a specific prospect
        required: false
        schema:
          type: string
          format: uuid
        example: 770e8400-e29b-41d4-a716-446655440003
      - name: filter[task][id]
        in: query
        description: Filter emails by the sequence task they were sent for. Matches Email.sepTaskId (null for emails unrelated to a sequence task).
        required: false
        schema:
          type: string
          format: uuid
        example: 990e8400-e29b-41d4-a716-446655440099
      - name: filter[account][id]
        in: query
        description: 'Filter emails associated with a specific account. Joins through

          the email''s prospect (`Prospect.accountId`); rows whose prospect

          has no account, or rows with no prospect, are excluded.

          '
        required: false
        schema:
          type: string
          format: uuid
        example: 990e8400-e29b-41d4-a716-446655440099
      - name: filter[status]
        in: query
        description: 'Filter emails by delivery status. Accepts a comma-separated list;

          rows matching any of the provided statuses are returned. Note that

          legacy rows may carry statuses outside this set (e.g. `delivered`,

          `sent_from_gmail`) — filtering is case-sensitive and exact, so

          those rows will not match `sent`.

          '
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - draft
            - in_progress
            - sent
            - failed
        style: form
        explode: false
        example:
        - sent
        - failed
      - $ref: '#/components/parameters/FilterUpdatedAtGte'
      - $ref: '#/components/parameters/FilterUpdatedAtLt'
      - name: include
        in: query
        description: 'Comma-separated relations to expand inline. Valid values: `prospect`, `sequence`, `sequenceStep`. Max 3.'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - prospect
            - sequence
            - sequenceStep
          maxItems: 3
        style: form
        explode: false
        example:
        - prospect
        - sequence
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Email'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /emails/{id}:
    get:
      operationId: getEmail
      summary: Get email by ID
      description: 'Returns a single email by its unique identifier.


        Example:

        ```bash

        curl -X GET ''https://partner-api.nooks.in/v1/emails/550e8400-e29b-41d4-a716-446655440000'' \

        -H "Authorization: Bearer nooks-api-..."

        ```'
      tags:
      - Emails
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier for the email
        schema:
          type: string
          format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: include
        in: query
        description: 'Comma-separated relations to expand inline. Valid values: `prospect`, `sequence`, `sequenceStep`. Max 3.'
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - prospect
            - sequence
            - sequenceStep
          maxItems: 3
        style: form
        explode: false
        example:
        - prospect
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Email:
      type: object
      description: An email record
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the email
        type:
          type: string
          nullable: true
          description: Integration type of the email
        status:
          type: string
          nullable: true
          description: Current status of the email
        from:
          type: string
          nullable: true
          description: Sender email address
        to:
          type: string
          nullable: true
          description: Recipient email address
        recipients:
          type: array
          nullable: true
          items:
            type: string
          description: List of recipient email addresses
        subject:
          type: string
          nullable: true
          description: Email subject line
        bodyText:
          type: string
          nullable: true
          description: The plain-text body of the email.
        bodyHtml:
          type: string
          nullable: true
          description: The HTML body of the email.
        prospect:
          nullable: true
          description: Associated prospect
          allOf:
          - $ref: '#/components/schemas/ReferenceObject'
        sequence:
          nullable: true
          description: 'Sequence associated with this email when matched to a Nooks SEP task.

            Null when the email is not matched to a Nooks SEP task.

            '
          allOf:
          - $ref: '#/components/schemas/ReferenceObject'
        sequenceStep:
          nullable: true
          description: 'Sequence step associated with this email when matched to a Nooks SEP task.

            Null when the email is not matched to a Nooks SEP task.

            '
          allOf:
          - $ref: '#/components/schemas/ReferenceObject'
        date:
          type: string
          format: date-time
          nullable: true
          description: Date of the email
        deliveredAt:
          type: string
          format: date-time
          nullable: true
          description: When the email was delivered
        openedAt:
          type: string
          format: date-time
          nullable: true
          description: When the email was first opened
        clickedAt:
          type: string
          format: date-time
          nullable: true
          description: When a link in the email was first clicked
        bouncedAt:
          type: string
          format: date-time
          nullable: true
          description: When the email bounced
        repliedAt:
          type: string
          format: date-time
          nullable: true
          description: When a reply was received
        openCount:
          type: integer
          nullable: true
          description: Number of times the email was opened
        clickCount:
          type: integer
          nullable: true
          description: Number of times links were clicked
        createdAt:
          type: string
          format: date-time
          description: When the email record was created
        updatedAt:
          type: string
          format: date-time
          description: When the email record was last updated
      required:
      - id
      - prospect
      - sequence
      - sequenceStep
      - createdAt
      - updatedAt
    PaginationLinks:
      type: object
      description: 'Pagination links for navigating through results.

        Links are returned as relative references (path + query) that

        should be resolved against the base URL of the request.

        '
      properties:
        first:
          type: string
          format: uri-reference
          description: URL for the first page
          example: /v1/sequences?page[size]=50
        prev:
          type: string
          format: uri-reference
          nullable: true
          description: URL for the previous page (null if on first page)
          example: null
        next:
          type: string
          format: uri-reference
          nullable: true
          description: URL for the next page (null if on last page)
          example: /v1/sequences?page[size]=50&page[after]=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
    Error:
      type: object
      description: Standard error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: NOT_FOUND
            message:
              type: string
              description: Human-readable error message
              example: The requested resource was not found
        traceId:
          type: string
          description: 'Request trace identifier for correlating this error with server

            logs and support requests. Present whenever the request carried a

            trace context (the normal case); omitted otherwise.

            '
          example: abc123def456
    ReferenceObject:
      type: object
      description: A reference to a related resource
      properties:
        id:
          type: string
          description: Unique identifier of the referenced resource
          example: 550e8400-e29b-41d4-a716-446655440000
        _href:
          type: string
          description: API path to the referenced resource
          example: /v1/sequences/550e8400-e29b-41d4-a716-446655440000
      required:
      - id
      - _href
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing API key
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: The requested resource was not found
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid page[after] cursor
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
  parameters:
    PageSize:
      name: page[size]
      in: query
      description: Number of items per page (max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
      example: 50
    FilterUpdatedAtLt:
      name: filter[updatedAt][lt]
      in: query
      description: Filter by updatedAt before this timestamp, exclusive (ISO 8601 datetime)
      required: false
      schema:
        type: string
        format: date-time
      example: '2026-01-01T00:00:00Z'
    FilterId:
      name: filter[id]
      in: query
      description: Filter by IDs (comma-separated UUIDs). An empty value is treated as "no filter".
      required: false
      schema:
        type: string
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(,[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})*)?$
      example: 550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001
    PageAfter:
      name: page[after]
      in: query
      description: 'Cursor for fetching the next page. Opaque token returned by the

        API in `links.next`; callers should treat it as opaque and only

        pass values they received from a previous response. Malformed

        cursors return `400 Bad Request`.

        '
      required: false
      schema:
        type: string
      example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
    FilterUpdatedAtGte:
      name: filter[updatedAt][gte]
      in: query
      description: Filter by minimum updatedAt (ISO 8601 datetime)
      required: false
      schema:
        type: string
        format: date-time
      example: '2025-01-01T00:00:00Z'
    PageBefore:
      name: page[before]
      in: query
      description: 'Cursor for fetching the previous page. Opaque token returned by

        the API in `links.prev`; callers should treat it as opaque and

        only pass values they received from a previous response.

        Malformed cursors return `400 Bad Request`.

        '
      required: false
      schema:
        type: string
      example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInYiOjF9
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token sent in the `Authorization` header. Accepts either a

        long-lived Nooks API key (`nooks-api-...`, from Developer Settings →

        API Keys) or an OAuth 2.0 access token issued by

        `https://oauth.nooks.in`. Use whichever you already have — the API

        validates both formats on the same header. For full OAuth flow

        details (authorize/token endpoints, scopes, refresh behavior) see

        the Authentication section of this spec''s introduction.

        '
x-tagGroups:
- name: API Reference
  tags:
  - Sequences
  - SequenceSteps
  - Emails
  - Users
  - SequenceStates
  - Prospects
  - Accounts
  - Notes
  - Mailboxes
  - Calls
  - CallDispositions
  - Tasks
  - EmailTemplates
  - Introspection