Plover

An IMAP4rev2 (RFC 9051) client library for Elixir.

Plover provides a high-level API for connecting to IMAP servers over implicit TLS, authenticating, managing mailboxes, and fetching/searching/storing messages.

Disclaimer

While I did my best to ensure this library works and am starting to use it in another application, please be aware that it was generated with a generous dosage of help from AI and should not be considered production ready.

Features

• Full IMAP4rev2 command set: LOGIN, AUTHENTICATE (PLAIN, XOAUTH2), SELECT, EXAMINE, FETCH, SEARCH, STORE, COPY, MOVE, IDLE, APPEND, and more
• UID variants for all message commands
• ESEARCH response parsing (MIN, MAX, COUNT, ALL)
• IDLE for real-time mailbox notifications
• Envelope, body structure, and flag parsing
• Each connection is a supervised GenServer with a clean state machine

Quick Start

# Connect over implicit TLS (port 993)
{:ok, conn} = Plover.connect("imap.example.com")

# Authenticate
{:ok, _} = Plover.login(conn, "user@example.com", "password")

# Select a mailbox
{:ok, _} = Plover.select(conn, "INBOX")

# Fetch messages
{:ok, messages} = Plover.fetch(conn, "1:5", [:envelope, :flags, :uid])

for msg <- messages do
  IO.puts("#{msg.attrs.uid}: #{msg.attrs.envelope.subject}")
end

# Search
{:ok, results} = Plover.search(conn, "UNSEEN")
IO.puts("#{results.count} unseen messages")

# IDLE for real-time updates
:ok = Plover.idle(conn, fn update -> IO.inspect(update) end)
# ... later ...
{:ok, _} = Plover.idle_done(conn)

# Clean up
{:ok, _} = Plover.logout(conn)

Architecture

Plover              Public API facade
  |
Connection          GenServer: socket I/O, command dispatch, state machine
  |
Protocol            Tokenizer (NimbleParsec), Parser, Command Builder
  |
Transport           Behaviour: SSL (production) / Mock (testing)

Installation

Add plover to your list of dependencies in mix.exs:

def deps do
  [
    {:plover, "~> 0.1.0"}
  ]
end