openapi: 3.2.0
info:
  title: CRM API Reference Emails API
  version: '2.0'
  summary: API
servers:
- url: https://api.vessel.dev
security:
- VesselAPIToken: []
tags:
- name: emails
paths:
  /crm/emails:
    parameters: []
    get:
      summary: Get All Emails
      tags:
      - emails
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  emails:
                    type: array
                    items:
                      $ref: '#/components/schemas/Email'
                  nextPageCursor:
                    type: string
                title: responseBody
              examples:
                example-1:
                  value:
                    emails:
                    - id: v.email.3ab3a9562af957228c1019127e3c81e1
                      nativeId: '23'
                      from: michael@dunder.mifflin
                      to:
                      - greg@bluecross.com
                      cc:
                      - betty@bluecross.com
                      bcc:
                      - carl@bluecross.com
                      subject: BlueCross <> Dunder Mifflin
                      body: Hi Greg, need any paper? - Michael
                      bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
                      messageDate: '2019-08-24T14:15:22Z'
                      isIncoming: false
                      isBounced: false
                      hasAttachment: false
                      status: SENT
                      createdTime: '2019-08-24T14:15:22Z'
                      modifiedTime: '2019-08-24T14:15:22Z'
                      associations:
                        accountIds:
                        - v.account.0dcb45e051315a6ea63b0f16e73689d9
                        leadIds:
                        - v.lead.d08f345ace24509e911a0ea8e3d2203c
                        contactIds:
                        - v.contact.e5f32d4fd2115220bd20a2ccf81210ec
                        dealIds:
                        - v.deal.497fb529e6805351b5dc8057c74a4a52
                        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                      additional: {}
                    nextPageCursor: string
      operationId: get-all-crm-emails
      description: Retrieve all Emails
      parameters:
      - schema:
          type: string
        in: query
        name: accessToken
        description: The token for the customer's CRM account. This was generated when they connected their account.
        required: true
      - schema:
          type: string
        in: query
        name: cursor
      - schema:
          type: number
        in: query
        name: limit
        description: The number of records to return per page.
      - schema:
          type: boolean
        in: query
        name: allFields
        description: Returns all fields including non-unifiable and custom fields under the "additional" property in the response
  /crm/emails/search:
    post:
      summary: Search Emails
      tags:
      - emails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    id:
                      $ref: '#/components/schemas/StringFilter'
                    nativeId:
                      $ref: '#/components/schemas/StringFilter'
                    from:
                      $ref: '#/components/schemas/StringFilter'
                    to:
                      $ref: '#/components/schemas/StringListFilter'
                    cc:
                      $ref: '#/components/schemas/StringListFilter'
                    bcc:
                      $ref: '#/components/schemas/StringListFilter'
                    subject:
                      $ref: '#/components/schemas/StringFilter'
                    body:
                      $ref: '#/components/schemas/StringFilter'
                    bodyHtml:
                      $ref: '#/components/schemas/StringFilter'
                    messageDate:
                      $ref: '#/components/schemas/DateFilter'
                    isIncoming:
                      $ref: '#/components/schemas/BooleanFilter'
                    isBounced:
                      $ref: '#/components/schemas/BooleanFilter'
                    hasAttachment:
                      $ref: '#/components/schemas/BooleanFilter'
                    status:
                      $ref: '#/components/schemas/StringFilter'
                    createdTime:
                      $ref: '#/components/schemas/DateFilter'
                    modifiedTime:
                      $ref: '#/components/schemas/DateFilter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  emails:
                    type: array
                    items:
                      $ref: '#/components/schemas/Email'
                  nextPageCursor:
                    type: string
                title: responseBody
              examples:
                example-1:
                  value:
                    emails:
                    - id: v.email.3ab3a9562af957228c1019127e3c81e1
                      nativeId: '23'
                      from: michael@dunder.mifflin
                      to:
                      - greg@bluecross.com
                      cc:
                      - betty@bluecross.com
                      bcc:
                      - carl@bluecross.com
                      subject: BlueCross <> Dunder Mifflin
                      body: Hi Greg, need any paper? - Michael
                      bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
                      messageDate: '2019-08-24T14:15:22Z'
                      isIncoming: false
                      isBounced: false
                      hasAttachment: false
                      status: SENT
                      createdTime: '2019-08-24T14:15:22Z'
                      modifiedTime: '2019-08-24T14:15:22Z'
                      associations:
                        accountIds:
                        - v.account.0dcb45e051315a6ea63b0f16e73689d9
                        leadIds:
                        - v.lead.d08f345ace24509e911a0ea8e3d2203c
                        contactIds:
                        - v.contact.e5f32d4fd2115220bd20a2ccf81210ec
                        dealIds:
                        - v.deal.497fb529e6805351b5dc8057c74a4a52
                        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                      additional: {}
                    nextPageCursor: string
      operationId: search-crm-emails
      description: Search all Emails using filters
      parameters:
      - $ref: '#/components/parameters/accessToken'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/allFields'
  /crm/email:
    parameters: []
    get:
      summary: Get Email
      tags:
      - emails
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    $ref: '#/components/schemas/Email'
                title: responseBody
              examples:
                example-1:
                  value:
                    email:
                      id: v.email.3ab3a9562af957228c1019127e3c81e1
                      nativeId: '23'
                      from: michael@dunder.mifflin
                      to:
                      - greg@bluecross.com
                      cc:
                      - betty@bluecross.com
                      bcc:
                      - carl@bluecross.com
                      subject: BlueCross <> Dunder Mifflin
                      body: Hi Greg, need any paper? - Michael
                      bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
                      messageDate: '2019-08-24T14:15:22Z'
                      isIncoming: false
                      isBounced: false
                      hasAttachment: false
                      status: SENT
                      createdTime: '2019-08-24T14:15:22Z'
                      modifiedTime: '2019-08-24T14:15:22Z'
                      associations:
                        accountIds:
                        - v.account.0dcb45e051315a6ea63b0f16e73689d9
                        leadIds:
                        - v.lead.d08f345ace24509e911a0ea8e3d2203c
                        contactIds:
                        - v.contact.e5f32d4fd2115220bd20a2ccf81210ec
                        dealIds:
                        - v.deal.497fb529e6805351b5dc8057c74a4a52
                        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                      additional: {}
      operationId: get-one-crm-email
      parameters:
      - schema:
          type: string
        in: query
        name: accessToken
        description: The token for the customer's CRM account. This was generated when they connected their account.
        required: true
      - schema:
          type: string
        in: query
        name: id
        required: true
      - schema:
          type: boolean
        in: query
        name: allFields
        description: Returns all fields including non-unifiable and custom fields under the "additional" property in the response
      description: Retrieve a single Task by Id
    post:
      summary: Create Email
      tags:
      - emails
      operationId: post-crm-email
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                description: ''
                type: object
                x-examples:
                  example-1:
                    id: '0'
                properties:
                  id:
                    type: string
                required:
                - id
              examples:
                example-1:
                  value:
                    id: '0'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                email:
                  $ref: '#/components/schemas/EmailCreate'
              required:
              - accessToken
            examples:
              example-1:
                value:
                  accessToken: string
                  email:
                    from: michael@dunder.mifflin
                    to:
                    - greg@bluecross.com
                    cc:
                    - betty@bluecross.com
                    bcc:
                    - carl@bluecross.com
                    subject: BlueCross <> Dunder Mifflin
                    body: Hi Greg, need any paper? - Michael
                    bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
                    messageDate: '2019-08-24T14:15:22Z'
                    isIncoming: false
                    status: SENT
                    accountId: v.account.0dcb45e051315a6ea63b0f16e73689d9
                    dealId: v.deal.497fb529e6805351b5dc8057c74a4a52
                    leads:
                    - id: v.lead.d08f345ace24509e911a0ea8e3d2203c
                      role: to
                    contacts:
                    - id: v.contact.e5f32d4fd2115220bd20a2ccf81210ec
                      role: cc
                    ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                    additional: {}
        description: ''
      description: Create a new Email.
    patch:
      summary: Update Email
      tags:
      - emails
      operationId: put-crm-email
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: responseBody
                description: ''
                type: object
                x-examples:
                  example-1:
                    id: '0'
                properties:
                  id:
                    type: string
                required:
                - id
              examples:
                example-1:
                  value:
                    id: '0'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                accessToken:
                  type: string
                id:
                  type: string
                email:
                  $ref: '#/components/schemas/EmailUpdate'
              required:
              - accessToken
              - id
              - email
            examples:
              example-1:
                value:
                  accessToken: string
                  id: string
                  email:
                    isIncoming: false
                    status: SENT
                    ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                    additional: {}
      description: 'Update an Email by Id.

        *CRM Caveats*:

        - Pipedrive: Not supported.'
  /crm/email/details:
    get:
      summary: Get Email Details
      tags:
      - emails
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      $ref: '#/components/schemas/Field'
                  nextPageCursor:
                    type: string
                title: responseBody
              examples:
                example-1:
                  value:
                    fields:
                    - key: email
                      name: Email
                      type: email
                      options: null
                      isArray: false
                      custom: false
                      universal: true
                      required: false
                      creatable: true
                      updatable: true
                    nextPageCursor: string
      operationId: get-details-crm-email
      description: 'Get details about all emails.

        Details include the type, possible values, and other meta data about the fields.'
      parameters:
      - schema:
          type: string
        in: query
        name: accessToken
        description: The token for the customer's CRM account. This was generated when they connected their account.
        required: true
      - schema:
          type: string
        in: query
        name: cursor
      - schema:
          type: boolean
        in: query
        name: allFields
        description: Returns details about native fields.
  /crm/email/batch:
    parameters: []
    get:
      summary: Get Batch Emails
      tags:
      - emails
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  emails:
                    type: array
                    items:
                      $ref: '#/components/schemas/Email'
                  invalidIds:
                    $ref: '#/components/schemas/InvalidIds'
                title: responseBody
              examples:
                example-1:
                  value:
                    email:
                      id: v.email.3ab3a9562af957228c1019127e3c81e1
                      nativeId: '23'
                      from: michael@dunder.mifflin
                      to:
                      - greg@bluecross.com
                      cc:
                      - betty@bluecross.com
                      bcc:
                      - carl@bluecross.com
                      subject: BlueCross <> Dunder Mifflin
                      body: Hi Greg, need any paper? - Michael
                      bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
                      messageDate: '2019-08-24T14:15:22Z'
                      isIncoming: false
                      isBounced: false
                      hasAttachment: false
                      status: SENT
                      createdTime: '2019-08-24T14:15:22Z'
                      modifiedTime: '2019-08-24T14:15:22Z'
                      associations:
                        accountIds:
                        - v.account.0dcb45e051315a6ea63b0f16e73689d9
                        leadIds:
                        - v.lead.d08f345ace24509e911a0ea8e3d2203c
                        contactIds:
                        - v.contact.e5f32d4fd2115220bd20a2ccf81210ec
                        dealIds:
                        - v.deal.497fb529e6805351b5dc8057c74a4a52
                        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
                      additional: {}
      operationId: get-batch-crm-email
      parameters:
      - schema:
          type: string
        in: query
        name: accessToken
        required: true
        description: The token for the customer's CRM account. This was generated when they connected their account.
      - schema:
          type: string
        in: query
        name: ids
        description: Comma separated list of Email Id's.
      - schema:
          type: boolean
        in: query
        name: allFields
        description: Returns all fields including non-unifiable and custom fields under the "additional" property in the response
      description: Retrieve Email by a set of Id's
components:
  schemas:
    DateFilter:
      type: object
      properties:
        equals:
          type: string
        gt:
          type: string
        lt:
          type: string
        lte:
          type: string
        gte:
          type: string
        not:
          type: string
        in:
          type: array
          items:
            type: string
        notIn:
          type: array
          items:
            type: string
    StringListFilter:
      type: object
      properties:
        has:
          type: string
        hasEvery:
          type: array
          items:
            type: string
        hasSome:
          type: array
          items:
            type: string
        isEmpty:
          type: boolean
    InvalidIds:
      type: array
      items:
        type: string
      description: Ids that didn't return anything. Will be an empty array if all Ids are valid.
    BooleanFilter:
      type: object
      properties:
        equals:
          type: boolean
        not:
          type: boolean
    Email:
      title: Email
      type: object
      description: An email is a message sent from one person to another through an email service. Emails involve participants - the person who the email was sent to, or the person that sent it. Participants are usually a Contact, Lead, or User but in certain CRMs, can be a person not yet associated with a CRM object.
      examples:
      - id: v.email.3ab3a9562af957228c1019127e3c81e1
        nativeId: '23'
        from: michael@dunder.mifflin
        to:
        - greg@bluecross.com
        cc:
        - betty@bluecross.com
        bcc:
        - carl@bluecross.com
        subject: BlueCross <> Dunder Mifflin
        body: Hi Greg, need any paper? - Michael
        bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
        messageDate: '2019-08-24T14:15:22Z'
        isIncoming: false
        isBounced: false
        hasAttachment: false
        status: SENT
        createdTime: '2019-08-24T14:15:22Z'
        modifiedTime: '2019-08-24T14:15:22Z'
        associations:
          accountIds:
          - v.account.0dcb45e051315a6ea63b0f16e73689d9
          leadIds:
          - v.lead.d08f345ace24509e911a0ea8e3d2203c
          contactIds:
          - v.contact.e5f32d4fd2115220bd20a2ccf81210ec
          dealIds:
          - v.deal.497fb529e6805351b5dc8057c74a4a52
          ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
        additional: {}
      properties:
        id:
          type: string
          description: Unique Vessel Id.
        nativeId:
          type: string
          description: Id of the object in the connected CRM.
        from:
          type: string
          description: The email address that sent the email
        to:
          type: array
          description: The email addresses that received the email
          items:
            type: string
        cc:
          type: array
          description: The email addresses that received a copy of the email
          items:
            type: string
        bcc:
          type: array
          description: The email addresses that received a blind copy of the email
          items:
            type: string
        subject:
          type: string
          description: The subject of the email
        body:
          type: string
          description: The text formatted body of the email
        bodyHtml:
          type: string
          description: The html formatted body of the email
        messageDate:
          type: string
          description: The date the email was created. This can be set when creating the email object and is not necessarily the same as the `createdTime` field.
        isIncoming:
          type: boolean
          description: If this email was sent to the user or sent by the user
        isBounced:
          type: boolean
          description: If this email was bounced
        hasAttachment:
          type: boolean
          description: If this email has attachment(s)
        status:
          type: string
          description: The status of the email (CRM specific, see /details).
        createdTime:
          type: string
          description: The timestamp that the email object was created
        modifiedTime:
          type: string
          description: The timestamp the email object was last modified
        associations:
          type: object
          required:
          - accountIds
          - leadIds
          - contactIds
          - dealIds
          - ownerUserId
          properties:
            accountIds:
              type: array
              items:
                type: string
            leadIds:
              type: array
              items:
                type: string
            contactIds:
              type: array
              items:
                type: string
            dealIds:
              type: array
              items:
                type: string
            ownerUserId:
              type: string
              description: The Id of the User that owns this email
        additional:
          type: object
          description: Returned when `allFields` is set in the query params. Includes all data, untransformed, we received from the downstream CRM
      required:
      - id
      - nativeId
      - from
      - to
      - subject
      - createdTime
      - modifiedTime
      - associations
    EmailCreate:
      title: EmailCreate
      type: object
      description: ''
      examples:
      - from: michael@dunder.mifflin
        to:
        - greg@bluecross.com
        cc:
        - betty@bluecross.com
        bcc:
        - carl@bluecross.com
        subject: BlueCross <> Dunder Mifflin
        body: Hi Greg, need any paper? - Michael
        bodyHtml: <p>Hi Greg, need any paper? - Michael</p>
        messageDate: '2019-08-24T14:15:22Z'
        isIncoming: false
        status: SENT
        accountId: v.account.0dcb45e051315a6ea63b0f16e73689d9
        dealId: v.deal.497fb529e6805351b5dc8057c74a4a52
        leads:
        - id: v.lead.d08f345ace24509e911a0ea8e3d2203c
          role: to
        contacts:
        - id: v.contact.e5f32d4fd2115220bd20a2ccf81210ec
          role: cc
        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
        additional: {}
      properties:
        from:
          type: string
          description: The email address that sent the email
        to:
          type: array
          description: The email addresses that received the email
          items:
            type: string
        cc:
          type: array
          description: The email addresses that received a copy of the email
          items:
            type: string
        bcc:
          type: array
          description: The email addresses that received a blind copy of the email
          items:
            type: string
        subject:
          type: string
          description: The subject of the email
        body:
          type: string
          description: The text formatted body of the email
        bodyHtml:
          type: string
          description: The html formatted body of the email
        messageDate:
          type: string
          description: The date the email was created. This can be set when creating the email object and is not necessarily the same as the `createdTime` field.
        isIncoming:
          type: boolean
          description: If this email was sent to the user or sent by the user
        status:
          type: string
          description: The status of the email (CRM specific, see /details).
        accountId:
          type: string
        dealId:
          type: string
        lead:
          type: object
          description: Associated Leads must participate in the email (i.e., have a role).
          properties:
            id:
              type: string
            role:
              enum:
              - from
              - to
              - cc
              - bcc
        contact:
          type: object
          description: Associated Contacts must participate in the email (i.e., have a role).
          properties:
            id:
              type: string
            role:
              enum:
              - from
              - to
              - cc
              - bcc
        ownerUserId:
          type: string
          description: The Id of the User that owns this email
        additional:
          type: object
          description: Create any property in the downstream CRM, such as a custom or native property. For a list of all properties see /details.
      required:
      - from
      - to
      - subject
    Field:
      title: Field
      type: object
      description: '(Alias: property) A field is a key-value pair on a CRM Object that provides information about that object.'
      properties:
        key:
          type: string
          description: 'The key in the CRM object (ex: annualRevenue, numberOfEmployees, etc)'
        name:
          type: string
          description: 'The display name of this field (ex: number of employees, annual revenue, etc)'
        type:
          type: string
          enum:
          - string
          - number
          - datetime
          - date
          - boolean
          - reference
          - phone
          - url
          - id
          - email
          - percent
          - singleselect
          - multiselect
          - address
          - decimal
          - time
          - daterange
          - object
        options:
          type: array
          description: Possible options for this field
          items:
            type: object
            properties:
              key:
                oneOf:
                - type: string
                - type: number
              name:
                type: string
        isArray:
          type: boolean
          description: If this field is an array
        custom:
          type: boolean
          description: If this field is a custom field
        universal:
          type: boolean
          description: If this is a field we've unified across CRMs
        required:
          type: boolean
          description: If this field is required when creating the object
        creatable:
          type: boolean
          description: If this field can be used when creating the object
        updatable:
          type: boolean
          description: If this field can be updated
      required:
      - key
      - name
      - type
      - custom
      - universal
      - required
      - creatable
      - updatable
      examples:
      - key: numberOfEmployees
        name: number of employees
        type: number
        options: null
        isArray: false
        custom: false
        universal: true
        required: false
        creatable: true
        updatable: true
    EmailUpdate:
      title: EmailUpdate
      type: object
      description: ''
      examples:
      - isIncoming: false
        status: SENT
        ownerUserId: v.user.56f653659ea9524b9e0fb0ba67e6f8a0
        additional: {}
      properties:
        isIncoming:
          type: boolean
          description: If this email was sent to the user or sent by the user
        status:
          type: string
          description: The status of the email (CRM specific, see /details).
        ownerUserId:
          type: string
          description: The Id of the User that owns this email
        additional:
          type: object
          description: Create any property in the downstream CRM, such as a custom or native property. For a list of all properties see /details.
    StringFilter:
      type: object
      properties:
        equals:
          type: string
        contains:
          type: string
        startsWith:
          type: string
        endsWith:
          type: string
        not:
          type: string
        in:
          type: array
          items:
            type: string
        notIn:
          type: array
          items:
            type: string
        mode:
          type: string
          enum:
          - insensitive
  parameters:
    cursor:
      name: cursor
      in: query
      description: The cursor to use for pagination
      schema:
        type: string
    accessToken:
      name: accessToken
      in: query
      description: The token for the customer's account. This was generated when they connected their account.
      required: true
      schema:
        type: string
    allFields:
      name: allFields
      in: query
      description: Returns all fields including non-unifiable and custom fields under the "additional" property in the response
      schema:
        type: boolean
    limit:
      name: limit
      in: query
      description: The number of records to return per page.
      schema:
        type: number
  securitySchemes:
    VesselAPIToken:
      name: vessel-api-token
      type: apiKey
      in: header