Pipedrive Mailbox API

openapi: 3.2.0
info:
  title: Pipedrive API v1 Activities Mailbox API
  version: 1.0.0
  description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

    '
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Mailbox
  description: 'Mailbox was designed to be the email control hub inside Pipedrive. Pipedrive supports all major providers (including Gmail, Outlook and also custom IMAP/SMTP). There are 2 options for syncing user emails: 2-way sync: Mail Connection is established with the mail provider (example Gmail). There can be only 1 active Mail Connection per user in company. 1-way sync: SmartBCC feature which stores the copies of email messages to Pipedrive by adding the SmartBCC specific address to mail recipients.

    '
paths:
  /mailbox/mailMessages/{id}:
    get:
      summary: Get one mail message
      description: Returns data about a specific mail message.
      x-token-cost: 2
      operationId: getMailMessage
      tags:
      - Mailbox
      security:
      - api_key: []
      - oauth2:
        - mail:read
        - mail:full
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: The ID of the mail message to fetch
      - in: query
        name: include_body
        schema:
          title: numberBooleanDefault0
          type: number
          default: 0
          enum:
          - 0
          - 1
        description: Whether to include the full message body or not. `0` = Don't include, `1` = Include.
      responses:
        '200':
          description: The mail messages that are being synced with Pipedrive
          content:
            application/json:
              schema:
                title: GetMailMessageResponse
                allOf:
                - type: object
                  title: MailServiceBaseResponse
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                    statusCode:
                      description: The email service specific status code and it is returned through the response body.
                      type: integer
                    statusText:
                      description: The status text of the response.
                      type: string
                    service:
                      description: The service name of the response.
                      type: string
                - type: object
                  properties:
                    data:
                      type: object
                      title: MailMessageData
                      properties:
                        id:
                          description: ID of the mail message.
                          type: integer
                        from:
                          type: array
                          description: The array of mail message sender (object)
                          items:
                            type: object
                            properties:
                              id:
                                description: ID of the mail participant
                                type: integer
                              email_address:
                                description: Mail address of the mail participant
                                type: string
                              name:
                                description: Name of the mail participant
                                type: string
                              linked_person_id:
                                description: ID of the linked person to the mail message
                                type: integer
                              linked_person_name:
                                description: Name of the linked person to the mail message
                                type: string
                              mail_message_party_id:
                                description: ID of the mail message participant
                                type: integer
                        to:
                          type: array
                          description: The array of mail message receiver (object)
                          items:
                            type: object
                            properties:
                              id:
                                description: ID of the mail participant
                                type: integer
                              email_address:
                                description: Mail address of the mail participant
                                type: string
                              name:
                                description: Name of the mail participant
                                type: string
                              linked_person_id:
                                description: ID of the linked person to the mail message
                                type: integer
                              linked_person_name:
                                description: Name of the linked person to the mail message
                                type: string
                              mail_message_party_id:
                                description: ID of the mail message participant
                                type: integer
                        cc:
                          type: array
                          description: The array of mail message copies (object)
                          items:
                            type: object
                            properties:
                              id:
                                description: ID of the mail participant
                                type: integer
                              email_address:
                                description: Mail address of the mail participant
                                type: string
                              name:
                                description: Name of the mail participant
                                type: string
                              linked_person_id:
                                description: ID of the linked person to the mail message
                                type: integer
                              linked_person_name:
                                description: Name of the linked person to the mail message
                                type: string
                              mail_message_party_id:
                                description: ID of the mail message participant
                                type: integer
                        bcc:
                          type: array
                          description: The array of mail message blind copies (object)
                          items:
                            type: object
                            properties:
                              id:
                                description: ID of the mail participant
                                type: integer
                              email_address:
                                description: Mail address of the mail participant
                                type: string
                              name:
                                description: Name of the mail participant
                                type: string
                              linked_person_id:
                                description: ID of the linked person to the mail message
                                type: integer
                              linked_person_name:
                                description: Name of the linked person to the mail message
                                type: string
                              mail_message_party_id:
                                description: ID of the mail message participant
                                type: integer
                        body_url:
                          type: string
                          description: The mail message body URL
                        account_id:
                          type: string
                          description: The connection account ID
                        user_id:
                          type: integer
                          description: ID of the user whom mail message will be assigned to
                        mail_thread_id:
                          type: integer
                          description: ID of the mail message thread
                        subject:
                          type: string
                          description: The subject of mail message
                        snippet:
                          type: string
                          description: The snippet of mail message. Snippet length is up to 225 characters.
                        mail_tracking_status:
                          type:
                          - string
                          - 'null'
                          description: The status of tracking mail message. Value is `null` if tracking is not enabled.
                          enum:
                          - opened
                          - not opened
                        mail_link_tracking_enabled_flag:
                          description: Whether the link tracking in mail message body is enabled.
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        read_flag:
                          description: Whether the mail message is read or not by the user
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        draft:
                          type: string
                          description: If the mail message has a draft status then the value is the mail message object as JSON formatted string, otherwise `null`.
                        draft_flag:
                          description: Whether the mail message is a draft or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        synced_flag:
                          description: Whether the mail message is synced with the provider or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        deleted_flag:
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                          description: Whether the mail message is deleted or not
                        has_body_flag:
                          description: Whether the mail message has a body or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        sent_flag:
                          description: Whether the mail message has been sent or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        sent_from_pipedrive_flag:
                          description: Whether the mail message has been sent from Pipedrive app or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        smart_bcc_flag:
                          description: Whether the mail message has been created by Smart Email BCC feature or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        message_time:
                          type: string
                          format: date-time
                          description: Creation or receival time of the mail message
                        add_time:
                          type: string
                          format: date-time
                          description: The insertion into the database time of the mail message
                        update_time:
                          type: string
                          format: date-time
                          description: The updating time in the database of the mail message
                        has_attachments_flag:
                          description: Whether the mail message has an attachment or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        has_inline_attachments_flag:
                          description: Whether the mail message has an inline attachment or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
                        has_real_attachments_flag:
                          description: Whether the mail message has an attachment (which is not inline) or not
                          allOf:
                          - title: numberBooleanDefault0
                            type: number
                            default: 0
                            enum:
                            - 0
                            - 1
              example:
                success: true
                statusCode: 2000
                statusText: Success
                service: email-api
                data:
                  id: 1
                  from:
                  - id: 1
                    email_address: mail@example.org
                    name: Test
                    linked_person_id: 1
                    linked_person_name: ''
                    mail_message_party_id: 1
                  to:
                  - id: 1
                    email_address: mail@example.org
                    name: Test
                    linked_person_id: 1
                    linked_person_name: ''
                    mail_message_party_id: 1
                  cc:
                  - id: 1
                    email_address: mail@example.org
                    name: Test
                    linked_person_id: 1
                    linked_person_name: ''
                    mail_message_party_id: 1
                  bcc:
                  - id: 1
                    email_address: mail@example.org
                    name: Test
                    linked_person_id: 1
                    linked_person_name: ''
                    mail_message_party_id: 1
                  body_url: https://example.org
                  account_id: test
                  user_id: 1
                  mail_thread_id: 1
                  subject: test subject
                  snippet: test subject
                  mail_tracking_status: opened
                  mail_link_tracking_enabled_flag: 0
                  read_flag: 1
                  draft: ''
                  draft_flag: 0
                  synced_flag: 1
                  deleted_flag: 0
                  has_body_flag: 1
                  sent_flag: 0
                  sent_from_pipedrive_flag: 0
                  smart_bcc_flag: 0
                  message_time: '2019-11-14T06:02:06.000Z'
                  add_time: '2019-11-14T06:02:06.000Z'
                  update_time: '2019-11-14T07:15:49.000Z'
                  has_attachments_flag: 1
                  has_inline_attachments_flag: 0
                  has_real_attachments_flag: 1
  /mailbox/mailThreads:
    get:
      summary: Get mail threads
      description: Returns mail threads in a specified folder ordered by the most recent message within.
      x-token-cost: 20
      operationId: getMailThreads
      tags:
      - Mailbox
      security:
      - api_key: []
      - oauth2:
        - mail:read
        - mail:full
      parameters:
      - in: query
        name: folder
        required: true
        schema:
          type: string
          enum:
          - inbox
          - drafts
          - sent
          - archive
          default: inbox
        description: The type of folder to fetch
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      responses:
        '200':
          description: Get mail threads
          content:
            application/json:
              schema:
                title: GetMailThreadResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: array
                      description: The array of mail threads
                      items:
                        title: MailThread
                        allOf:
                        - type: object
                          properties:
                            id:
                              type: integer
                              description: ID of the mail thread
                            account_id:
                              type: string
                              description: The connection account ID
                            user_id:
                              type: integer
                              description: ID of the user whom mail message will be assigned to
                            subject:
                              type: string
                              description: The subject
                            snippet:
                              type: string
                              description: A snippet
                            read_flag:
                              description: Whether the mail thread is read
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            mail_tracking_status:
                              type:
                              - string
                              - 'null'
                              description: Mail tracking status
                            has_attachments_flag:
                              description: Whether the mail thread has an attachment
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            has_inline_attachments_flag:
                              description: Whether the mail thread has inline attachments
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            has_real_attachments_flag:
                              description: Whether the mail thread has real attachments (which are not inline)
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            deleted_flag:
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                              description: Whether the mail thread is deleted
                            synced_flag:
                              description: Whether the mail thread is synced
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            smart_bcc_flag:
                              description: Whether one of the parties of the mail thread is Bcc
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            mail_link_tracking_enabled_flag:
                              description: Whether the link tracking of the mail thread is enabled
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                        - type: object
                          properties:
                            parties:
                              type: object
                              description: Parties of the mail thread
                              properties:
                                to:
                                  type: array
                                  description: Recipients of the mail thread
                                  items:
                                    type: object
                                    description: Member of a thread
                                    properties:
                                      id:
                                        type: integer
                                        description: ID of the mail thread participant
                                      name:
                                        type: string
                                        description: Name of the mail thread participant
                                      latest_sent:
                                        type: boolean
                                        description: Whether the mail thread participant was last to send an email
                                      email_address:
                                        type: string
                                        description: Email address of the mail thread participant
                                      message_time:
                                        type: number
                                        description: Message time
                                      linked_person_id:
                                        type: integer
                                        description: ID of the linked person
                                      linked_person_name:
                                        type: string
                                        description: Email of the linked person
                                      mail_message_party_id:
                                        type: integer
                                        description: ID of the mail message party
                                      linked_organization_id:
                                        type:
                                        - integer
                                        - 'null'
                                        description: Linked Organization ID
                                from:
                                  type: array
                                  description: Senders of the mail thread
                                  items:
                                    type: object
                                    description: Member of a thread
                                    properties:
                                      id:
                                        type: integer
                                        description: ID of the mail thread participant
                                      name:
                                        type: string
                                        description: Name of the mail thread participant
                                      latest_sent:
                                        type: boolean
                                        description: Whether the mail thread participant was last to send an email
                                      email_address:
                                        type: string
                                        description: Email address of the mail thread participant
                                      message_time:
                                        type: number
                                        description: Message time
                                      linked_person_id:
                                        type: integer
                                        description: ID of the linked person
                                      linked_person_name:
                                        type: string
                                        description: Email of the linked person
                                      mail_message_party_id:
                                        type: integer
                                        description: ID of the mail message party
                                      linked_organization_id:
                                        type:
                                        - integer
                                        - 'null'
                                        description: Linked Organization ID
                            drafts_parties:
                              type: array
                              description: Parties of the drafted mail thread
                              items:
                                type: object
                            folders:
                              type: array
                              description: Folders in which messages from thread are being stored
                              items:
                                type: string
                            version:
                              type: number
                              description: Version
                            snippet_draft:
                              type:
                              - string
                              - 'null'
                              description: A snippet from a draft
                            snippet_sent:
                              type: string
                              description: A snippet from a message sent
                            message_count:
                              type: integer
                              description: An amount of messages
                            has_draft_flag:
                              type: number
                              description: Whether the mail thread has any drafts
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            has_sent_flag:
                              type: number
                              description: Whether the mail thread has messages sent
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            archived_flag:
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                              description: Whether the mail thread is archived
                            shared_flag:
                              description: Whether the mail thread is shared
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            external_deleted_flag:
                              description: Whether the mail thread has been deleted externally
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            first_message_to_me_flag:
                              description: Whether the mail thread was initialized by others
                              allOf:
                              - title: numberBooleanDefault0
                                type: number
                                default: 0
                                enum:
                                - 0
                                - 1
                            last_message_timestamp:
                              type: string
                              format: date-time
                              description: Last message timestamp
                            first_message_timestamp:
                              type: string
                              format: date-time
                              description: The time when the mail thread has had the first message received or created
                            last_message_sent_timestamp:
                              type:
                              - string
                              - 'null'
                              format: date-time


# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-mailbox-api-openapi.yml