View Source ExPipedrive.Mailbox (ex_pipedrive v0.2.0)

API v1 client for the Pipedrive Mailbox (mail threads and messages).

Mailbox is Pipedrive's email hub: mail is synced into threads either via a 2-way Mail Connection (Gmail/Outlook/IMAP-SMTP) or 1-way via SmartBCC. There is no /api/v2 equivalent yet, so every function here explicitly routes to api_version: :v1.

Auth / scopes

Requires the mail:read OAuth scope for all read endpoints (list_threads/2, get_thread/2, list_thread_messages/2, get_message/3). update_thread/3 and delete_thread/2 additionally require mail:full. API-token clients need Mailbox access enabled on the authorizing user's Pipedrive account (2-way Mail Connection or SmartBCC) — without it these endpoints return empty results rather than an error.

Example

{:ok, threads} = ExPipedrive.Mailbox.list_threads(client, folder: "inbox")
{:ok, thread} = ExPipedrive.Mailbox.get_thread(client, thread.id)
{:ok, messages} = ExPipedrive.Mailbox.list_thread_messages(client, thread.id)
{:ok, message} = ExPipedrive.Mailbox.get_message(client, message.id, include_body: 1)
{:ok, thread} = ExPipedrive.Mailbox.update_thread(client, thread.id, %{deal_id: deal.id})
{:ok, :ok} = ExPipedrive.Mailbox.delete_thread(client, thread.id)

Summary

Functions

delete_thread(client, thread_id)

Marks a mail thread as deleted via DELETE /api/v1/mailbox/mailThreads/:id. Requires the mail:full scope.

get_message(client, message_id, opts \\ [])

Fetches a single mail message via GET /api/v1/mailbox/mailMessages/:id.

get_thread(client, thread_id)

Fetches a mail thread by id via GET /api/v1/mailbox/mailThreads/:id.

list_thread_messages(client, thread_id)

Lists all mail messages inside a thread via GET /api/v1/mailbox/mailThreads/:id/mailMessages.

list_threads(client, opts \\ [])

Lists mail threads in a folder via GET /api/v1/mailbox/mailThreads, ordered by the most recent message within each thread.

update_thread(client, thread_id, attrs)

Updates a mail thread's associations/flags via PUT /api/v1/mailbox/mailThreads/:id.

Functions

delete_thread(client, thread_id)

@spec delete_thread(Tesla.Client.t(), pos_integer()) ::
  {:ok, :ok} | {:error, ExPipedrive.Error.t()}

Marks a mail thread as deleted via DELETE /api/v1/mailbox/mailThreads/:id. Requires the mail:full scope.

Returns {:ok, :ok}.

get_message(client, message_id, opts \\ [])

@spec get_message(Tesla.Client.t(), pos_integer(), keyword()) ::
  {:ok, ExPipedrive.MailMessage.t()} | {:error, ExPipedrive.Error.t()}

Fetches a single mail message via GET /api/v1/mailbox/mailMessages/:id.

Options: :include_body — 0 (default, omit body) or 1 (include the full message body).

Returns {:ok, %MailMessage{}}.

get_thread(client, thread_id)

@spec get_thread(Tesla.Client.t(), pos_integer()) ::
  {:ok, ExPipedrive.MailThread.t()} | {:error, ExPipedrive.Error.t()}

Fetches a mail thread by id via GET /api/v1/mailbox/mailThreads/:id.

Returns {:ok, %MailThread{}}.

list_thread_messages(client, thread_id)

@spec list_thread_messages(Tesla.Client.t(), pos_integer()) ::
  {:ok, [ExPipedrive.MailMessage.t()]} | {:error, ExPipedrive.Error.t()}

Lists all mail messages inside a thread via GET /api/v1/mailbox/mailThreads/:id/mailMessages.

Returns {:ok, [%MailMessage{}]}.

list_threads(client, opts \\ [])

@spec list_threads(
  Tesla.Client.t(),
  keyword()
) :: {:ok, [ExPipedrive.MailThread.t()]} | {:error, ExPipedrive.Error.t()}

Lists mail threads in a folder via GET /api/v1/mailbox/mailThreads, ordered by the most recent message within each thread.

Options: :folder — one of "inbox" (default), "drafts", "sent", "archive"; :start (pagination offset, default 0); :limit (items per page).

Returns {:ok, [%MailThread{}]}.

update_thread(client, thread_id, attrs)

@spec update_thread(Tesla.Client.t(), pos_integer(), map()) ::
  {:ok, ExPipedrive.MailThread.t()} | {:error, ExPipedrive.Error.t()}

Updates a mail thread's associations/flags via PUT /api/v1/mailbox/mailThreads/:id.

Accepts a map with any of :deal_id, :lead_id, :shared_flag, :read_flag, :archived_flag. Requires the mail:full scope.

Returns {:ok, %MailThread{}}.