Affinity Emails API

openapi: 3.2.0
info:
  version: ''
  x-affinity-api-version: '2024-01-01'
  contact:
    email: support@affinity.co
    name: Affinity Support
    url: https://support.affinity.co
  description: '# Introduction


    Welcome to Affinity API v2!'
  license:
    name: Proprietary
    url: https://www.affinity.co/legal/terms-of-use
  termsOfService: https://www.affinity.co/legal/terms-of-use
  title: Affinity API v2 Emails API
  x-logo:
    url: https://s3.us-west-2.amazonaws.com/assets.affinity.co/img/logos/full-color-svg.svg
    altText: Affinity logo
servers:
- url: https://api.affinity.co
security:
- bearerAuth: []
tags:
- description: Operations about emails
  name: Emails
  x-stability-level: beta
paths:
  /v2/emails:
    get:
      x-stability-level: beta
      description: '| ⚠️ This endpoint is currently in BETA |

        |--|


        Paginate through all emails in Affinity. Returns basic information about the email interaction

        and its participants. Will only return emails or subject lines that the current authenticated

        user has permission to see. This endpoint is currently in a Closed Beta; to get access reach

        out to your Affinity CSM.'
      summary: Get metadata on all Emails
      operationId: v2_emails__GET
      tags:
      - Emails
      parameters:
      - name: cursor
        description: Cursor for the next or previous page
        in: query
        schema:
          type: string
          examples:
          - ICAgICAgYmVmb3JlOjo6Nw
        example: ICAgICAgYmVmb3JlOjo6Nw
      - name: limit
        description: Number of items to include in the page
        in: query
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 100
          examples:
          - 100
        example: 100
      - name: filter
        description: Filter options
        in: query
        schema:
          type: string
        example: id=1234
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/interactions.EmailPaged'
          headers:
            X-Ratelimit-Limit-User:
              $ref: '#/components/headers/X-Ratelimit-Limit-User'
            X-Ratelimit-Limit-User-Remaining:
              $ref: '#/components/headers/X-Ratelimit-Limit-User-Remaining'
            X-Ratelimit-Limit-User-Reset:
              $ref: '#/components/headers/X-Ratelimit-Limit-User-Reset'
            X-Ratelimit-Limit-Org:
              $ref: '#/components/headers/X-Ratelimit-Limit-Org'
            X-Ratelimit-Limit-Org-Remaining:
              $ref: '#/components/headers/X-Ratelimit-Limit-Org-Remaining'
            X-Ratelimit-Limit-Org-Reset:
              $ref: '#/components/headers/X-Ratelimit-Limit-Org-Reset'
        '400':
          $ref: '#/components/responses/400'
        default:
          $ref: '#/components/responses/default'
components:
  headers:
    X-Ratelimit-Limit-Org-Remaining:
      description: Number of requests remaining for the account
      schema:
        type: integer
    X-Ratelimit-Limit-User-Reset:
      description: Time in seconds before the limit resets for the user
      schema:
        type: integer
    X-Ratelimit-Limit-Org:
      description: Number of requests allowed per month for the account
      schema:
        type: integer
    X-Ratelimit-Limit-User:
      description: Number of requests allowed per minute for the user
      schema:
        type: integer
    X-Ratelimit-Limit-User-Remaining:
      description: Number of requests remaining for the user
      schema:
        type: integer
    X-Ratelimit-Limit-Org-Reset:
      description: Time in seconds before the limit resets for the account
      schema:
        type: integer
  schemas:
    AuthenticationError:
      title: AuthenticationError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - authentication
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: authentication
        message: 🚨 Error! Sound the alarm! 🚨
    Pagination:
      title: Pagination
      type: object
      properties:
        prevUrl:
          description: URL for the previous page
          type:
          - string
          - 'null'
          format: uri
          examples:
          - https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw
        nextUrl:
          description: URL for the next page
          type:
          - string
          - 'null'
          format: uri
          examples:
          - https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA
      examples:
      - prevUrl: https://api.affinity.co/v2/foo?cursor=ICAgICAgYmVmb3JlOjo6Nw
        nextUrl: https://api.affinity.co/v2/foo?cursor=ICAgICAgIGFmdGVyOjo6NA
    AuthorizationError:
      title: AuthorizationError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - authorization
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: authorization
        message: 🚨 Error! Sound the alarm! 🚨
    UnsupportedMediaTypeError:
      title: UnsupportedMediaTypeError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - unsupported-media-type
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: unsupported-media-type
        message: 🚨 Error! Sound the alarm! 🚨
    ValidationError:
      title: ValidationError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - validation
        message:
          description: Error message
          type: string
        param:
          description: Param the error refers to
          type: string
      required:
      - code
      - message
      - param
      additionalProperties: false
      examples:
      - code: validation
        param: limit
        message: 🚨 Error! Sound the alarm! 🚨
    UnprocessableEntityError:
      title: UnprocessableEntityError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - unprocessable-entity
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: unprocessable-entity
        message: 🚨 Error! Sound the alarm! 🚨
    interactions.Email:
      x-stability-level: beta
      title: interactions.Email
      type: object
      properties:
        id:
          description: The email's unique identifier
          type: integer
          format: int64
          minimum: 1
          maximum: 9007199254740991
          examples:
          - 1
        sentAt:
          description: The timestamp of when the email was sent
          type: string
          format: date-time
          examples:
          - '2023-01-01T00:00:00Z'
        loggingType:
          description: 'Indicates how the interaction was added to Affinity: either manually by a user (''manual'') or automatically through Affinity''s capture process (''automated''). Currently, emails can only be logged as ''automated''.'
          type: string
          examples:
          - automated
          enum:
          - automated
        direction:
          description: 'The direction of the email: ''sent'' if the email was sent by an internal user and  ''received'' if the email was sent to an internal user.'
          type: string
          enum:
          - sent
          - received
          examples:
          - received
        subject:
          description: The email's subject
          type:
          - string
          - 'null'
          examples:
          - Example subject
        createdAt:
          description: The timestamp of when the email was created
          type: string
          format: date-time
          examples:
          - '2023-01-01T00:00:00Z'
        updatedAt:
          description: The timestamp of when the email was updated
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2023-01-01T00:00:00Z'
        from:
          description: The participant who sent the email
          $ref: '#/components/schemas/Attendee'
        toParticipantsPreview:
          description: A preview of the participants in the 'To' field of the email
          $ref: '#/components/schemas/AttendeesPreview'
        ccParticipantsPreview:
          description: A preview of the participants who are cc'ed in the email
          $ref: '#/components/schemas/AttendeesPreview'
      required:
      - id
      - sentAt
      - loggingType
      - direction
      - subject
      - createdAt
      - updatedAt
      - from
      - toParticipantsPreview
      - ccParticipantsPreview
      additionalProperties: false
    ServerError:
      title: ServerError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - server
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: server
        message: 🚨 Error! Sound the alarm! 🚨
    AttendeesPreview:
      x-stability-level: beta
      title: interactions.AttendeesPreview
      type: object
      properties:
        data:
          description: A preview of Attendees
          type: array
          items:
            $ref: '#/components/schemas/Attendee'
          maxItems: 100
        totalCount:
          description: The total count of Attendees
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
          examples:
          - 200
      required:
      - data
      - totalCount
      additionalProperties: false
    interactions.EmailPaged:
      x-stability-level: beta
      title: interactions.EmailPaged
      description: EmailPaged model
      type: object
      properties:
        data:
          description: A page of Email results
          type: array
          items:
            $ref: '#/components/schemas/interactions.Email'
          maxItems: 100
        pagination:
          $ref: '#/components/schemas/PaginationWithTotalCount'
      required:
      - data
      - pagination
      additionalProperties: false
    RateLimitError:
      title: RateLimitError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - rate-limit
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: rate-limit
        message: 🚨 Error! Sound the alarm! 🚨
    NotImplementedError:
      title: NotImplementedError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - not-implemented
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: not-implemented
        message: 🚨 Error! Sound the alarm! 🚨
    NotAcceptableError:
      title: NotAcceptableError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - not-acceptable
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: not-acceptable
        message: 🚨 Error! Sound the alarm! 🚨
    Errors:
      title: Errors
      type: object
      properties:
        errors:
          description: Errors
          type: array
          items:
            $ref: '#/components/schemas/Error'
      required:
      - errors
      additionalProperties: false
    NotFoundError:
      title: NotFoundError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - not-found
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: not-found
        message: 🚨 Error! Sound the alarm! 🚨
    Attendee:
      title: Attendee
      type: object
      properties:
        emailAddress:
          description: The email addresses of the attendee
          type:
          - string
          - 'null'
          format: email
          examples:
          - john.smith@contoso.com
        person:
          oneOf:
          - $ref: '#/components/schemas/PersonData'
          - type: 'null'
      required:
      - emailAddress
      - person
      additionalProperties: false
    PaginationWithTotalCount:
      title: PaginationWithTotalCount
      type: object
      allOf:
      - $ref: '#/components/schemas/Pagination'
      properties:
        totalCount:
          description: The total count of the collection. Only included if requested via the totalCount query string parameter.
          type: integer
          format: int64
          minimum: 0
          maximum: 9007199254740991
    MethodNotAllowedError:
      title: MethodNotAllowedError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - method-not-allowed
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: method-not-allowed
        message: 🚨 Error! Sound the alarm! 🚨
    ConflictError:
      title: ConflictError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - conflict
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: conflict
        message: 🚨 Error! Sound the alarm! 🚨
    Error:
      title: Error
      oneOf:
      - $ref: '#/components/schemas/AuthenticationError'
      - $ref: '#/components/schemas/AuthorizationError'
      - $ref: '#/components/schemas/BadRequestError'
      - $ref: '#/components/schemas/ConflictError'
      - $ref: '#/components/schemas/MethodNotAllowedError'
      - $ref: '#/components/schemas/NotAcceptableError'
      - $ref: '#/components/schemas/NotFoundError'
      - $ref: '#/components/schemas/NotImplementedError'
      - $ref: '#/components/schemas/RateLimitError'
      - $ref: '#/components/schemas/ServerError'
      - $ref: '#/components/schemas/UnprocessableEntityError'
      - $ref: '#/components/schemas/UnsupportedMediaTypeError'
      - $ref: '#/components/schemas/ValidationError'
      discriminator:
        propertyName: code
        mapping:
          authentication: '#/components/schemas/AuthenticationError'
          authorization: '#/components/schemas/AuthorizationError'
          bad-request: '#/components/schemas/BadRequestError'
          conflict: '#/components/schemas/ConflictError'
          method-not-allowed: '#/components/schemas/MethodNotAllowedError'
          not-acceptable: '#/components/schemas/NotAcceptableError'
          not-found: '#/components/schemas/NotFoundError'
          not-implemented: '#/components/schemas/NotImplementedError'
          rate-limit: '#/components/schemas/RateLimitError'
          server: '#/components/schemas/ServerError'
          unprocessable-entity: '#/components/schemas/UnprocessableEntityError'
          unsupported-media-type: '#/components/schemas/UnsupportedMediaTypeError'
          validation: '#/components/schemas/ValidationError'
    PersonData:
      title: PersonData
      type: object
      properties:
        id:
          description: The persons's unique identifier
          type: integer
          format: int64
          minimum: 1
          maximum: 9007199254740991
          examples:
          - 1
        firstName:
          description: The person's first name
          type:
          - string
          - 'null'
          examples:
          - Jane
        lastName:
          description: The person's last name
          type:
          - string
          - 'null'
          examples:
          - Doe
        primaryEmailAddress:
          description: The person's primary email address
          type:
          - string
          - 'null'
          format: email
          examples:
          - jane.doe@acme.co
        type:
          description: The person's type
          type: string
          enum:
          - internal
          - external
          - collaborator
          examples:
          - internal
      required:
      - firstName
      - id
      - lastName
      - primaryEmailAddress
      - type
      additionalProperties: false
    BadRequestError:
      title: BadRequestError
      type: object
      properties:
        code:
          description: Error code
          type: string
          enum:
          - bad-request
        message:
          description: Error message
          type: string
      required:
      - code
      - message
      additionalProperties: false
      examples:
      - code: bad-request
        message: 🚨 Error! Sound the alarm! 🚨
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            title: responses.400
            type: object
            properties:
              errors:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/BadRequestError'
                  - $ref: '#/components/schemas/ValidationError'
                  discriminator:
                    propertyName: code
                    mapping:
                      bad-request: '#/components/schemas/BadRequestError'
                      validation: '#/components/schemas/ValidationError'
            required:
            - errors
            additionalProperties: false
      headers:
        X-Ratelimit-Limit-User:
          $ref: '#/components/headers/X-Ratelimit-Limit-User'
        X-Ratelimit-Limit-User-Remaining:
          $ref: '#/components/headers/X-Ratelimit-Limit-User-Remaining'
        X-Ratelimit-Limit-User-Reset:
          $ref: '#/components/headers/X-Ratelimit-Limit-User-Reset'
        X-Ratelimit-Limit-Org:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org'
        X-Ratelimit-Limit-Org-Remaining:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org-Remaining'
        X-Ratelimit-Limit-Org-Reset:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org-Reset'
    default:
      description: Errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
      headers:
        X-Ratelimit-Limit-User:
          $ref: '#/components/headers/X-Ratelimit-Limit-User'
        X-Ratelimit-Limit-User-Remaining:
          $ref: '#/components/headers/X-Ratelimit-Limit-User-Remaining'
        X-Ratelimit-Limit-User-Reset:
          $ref: '#/components/headers/X-Ratelimit-Limit-User-Reset'
        X-Ratelimit-Limit-Org:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org'
        X-Ratelimit-Limit-Org-Remaining:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org-Remaining'
        X-Ratelimit-Limit-Org-Reset:
          $ref: '#/components/headers/X-Ratelimit-Limit-Org-Reset'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer