Aurinko.API.Email (Aurinko v0.2.1)

Copy Markdown View Source

Aurinko Email API — messages, drafts, sync, and tracking.

Supports Gmail, Office 365, Outlook.com, MS Exchange, Zoho Mail, iCloud, and IMAP.

Sync Model

Aurinko uses a delta/token-based sync model. The typical workflow is:

  1. Call start_sync/2 to provision the sync.
  2. Call sync_updated/3 and sync_deleted/3 with the returned tokens for initial full sync.
  3. On subsequent syncs, reuse the next_delta_token for incremental updates.

Examples

# List inbox messages
{:ok, page} = Aurinko.Email.list_messages(token, limit: 25, q: "is:unread")

# Start sync
{:ok, sync} = Aurinko.Email.start_sync(token, days_within: 30)

# Get updated messages
{:ok, page} = Aurinko.Email.sync_updated(token, sync.sync_updated_token)

Summary

Functions

create_draft(token, params)

Create a new email draft.

delete_draft(token, id)

Delete a draft by ID.

get_attachment(token, message_id, attachment_id)

Download a specific attachment.

get_message(token, id, opts \\ [])

Get a single email message by ID.

list_attachments(token, message_id)

List attachments for a given message.

list_messages(token, opts \\ [])

List email messages. Optionally filter with query operators.

send_message(token, params)

Send a new email message.

start_sync(token, opts \\ [])

Start or resume an email sync. Returns delta tokens when ready.

sync_deleted(token, delta_token, opts \\ [])

Fetch deleted email IDs since the last sync.

sync_updated(token, delta_token, opts \\ [])

Fetch updated (new or modified) emails since the last sync.

update_message(token, id, params)

Mark a message as read or unread.

Functions

create_draft(token, params)

@spec create_draft(String.t(), map()) :: {:ok, map()} | {:error, Aurinko.Error.t()}

Create a new email draft.

delete_draft(token, id)

@spec delete_draft(String.t(), String.t()) :: :ok | {:error, Aurinko.Error.t()}

Delete a draft by ID.

get_attachment(token, message_id, attachment_id)

@spec get_attachment(String.t(), String.t(), String.t()) ::
  {:ok, binary()} | {:error, Aurinko.Error.t()}

Download a specific attachment.

get_message(token, id, opts \\ [])

@spec get_message(String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Email.t()} | {:error, Aurinko.Error.t()}

Get a single email message by ID.

Options

  • :body_type — "html" or "text" (default: "text")

list_attachments(token, message_id)

@spec list_attachments(String.t(), String.t()) ::
  {:ok, [map()]} | {:error, Aurinko.Error.t()}

List attachments for a given message.

list_messages(token, opts \\ [])

@spec list_messages(
  String.t(),
  keyword()
) :: {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

List email messages. Optionally filter with query operators.

Options

  • :limit — Number of messages to return (default: 20, max: 200)
  • :page_token — Token for pagination
  • :q — Search query string (e.g. "from:user@example.com", "is:unread")
  • :body_type — "html" or "text" (default: "text")
  • :load_body — Whether to load message body (default: false)

Examples

{:ok, page} = Aurinko.Email.list_messages(token,
  limit: 10,
  q: "from:[email protected]",
  load_body: true
)

send_message(token, params)

@spec send_message(String.t(), map()) ::
  {:ok, Aurinko.Types.Email.t()} | {:error, Aurinko.Error.t()}

Send a new email message.

Parameters

  • :to — List of recipient addresses (required). e.g. [%{address: "user@example.com", name: "User"}]
  • :subject — Email subject
  • :body — Email body content
  • :body_type — "html" or "text"
  • :cc — CC recipients
  • :bcc — BCC recipients
  • :reply_to_message_id — ID of message being replied to
  • :tracking — Tracking options map (:opens, :thread_replies, :context)

Examples

{:ok, message} = Aurinko.Email.send_message(token, %{
  to: [%{address: "[email protected]"}],
  subject: "Hello",
  body: "<h1>Hello!</h1>",
  body_type: "html",
  tracking: %{opens: true, thread_replies: true}
})

start_sync(token, opts \\ [])

@spec start_sync(
  String.t(),
  keyword()
) :: {:ok, Aurinko.Types.SyncResult.t()} | {:error, Aurinko.Error.t()}

Start or resume an email sync. Returns delta tokens when ready.

Options

  • :days_within — Limit initial scan to emails received in the past N days
  • :await_ready — Block until sync is ready (default: false)

Examples

{:ok, %SyncResult{ready: true, sync_updated_token: token}} =
  Aurinko.Email.start_sync(access_token, days_within: 30)

sync_deleted(token, delta_token, opts \\ [])

@spec sync_deleted(String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

Fetch deleted email IDs since the last sync.

sync_updated(token, delta_token, opts \\ [])

@spec sync_updated(String.t(), String.t(), keyword()) ::
  {:ok, Aurinko.Types.Pagination.t()} | {:error, Aurinko.Error.t()}

Fetch updated (new or modified) emails since the last sync.

Pass delta_token on the first call and then next_delta_token/next_page_token from each subsequent response.

Options

  • :body_type — "html" or "text"
  • :load_body — Whether to load message bodies

update_message(token, id, params)

@spec update_message(String.t(), String.t(), map()) ::
  {:ok, Aurinko.Types.Email.t()} | {:error, Aurinko.Error.t()}

Mark a message as read or unread.