Listmonk Elixir Client

Elixir client for the Listmonk open-source, self-hosted email platform.

Built with Req HTTP client and designed for easy integration into Elixir applications.

Note: This library is based on the Python Listmonk client by Michael Kennedy, adapted to idiomatic Elixir patterns and conventions.

Features

➕ Add and manage subscribers with custom attributes
🔍 Search subscribers using SQL queries
📋 Manage mailing lists (create, read, delete)
📧 Send transactional emails with template support and attachments
📨 Create and manage campaigns (bulk emails)
🎨 Manage templates for consistent email design
🏥 Health checks for instance connectivity
🔐 Flexible authentication via environment variables or runtime config
✨ Both safe and bang variants for all operations (get/1 and get!/1)

Installation

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

def deps do
  [
    {:listmonk_client, "~> 0.3.0"}
  ]
end

Quick Start

Configuration

Configure at runtime using a struct or keyword list:

# Using a struct
config = %Listmonk.Config{
  url: "https://listmonk.example.com",
  username: "admin",
  password: "your_password_or_api_key"
}

# Or using a keyword list
config = [
  url: "https://listmonk.example.com",
  username: "admin",
  password: "your_password_or_api_key"
]

For local development, you can also use environment variables:

cp .env.example .env
# Edit .env with your Listmonk instance details

Then load from environment:

config = Listmonk.Config.from_env()

Basic Usage

# Start a client with a named alias
{:ok, _pid} = Listmonk.new(config, :listmonk)

# Check health
{:ok, true} = Listmonk.healthy?(:listmonk)

# Get all lists
{:ok, lists} = Listmonk.get_lists(:listmonk)

# Create a subscriber
{:ok, subscriber} = Listmonk.create_subscriber(:listmonk, %{
  email: "user@example.com",
  name: "Jane Doe",
  lists: [1],
  attribs: %{"city" => "Portland"}
})

# Send a transactional email
{:ok, sent} = Listmonk.send_transactional_email(:listmonk, %{
  subscriber_email: "user@example.com",
  template_id: 3,
  data: %{
    full_name: "Jane Doe",
    reset_code: "abc123"
  }
})

# Stop the client when done
:ok = Listmonk.stop(:listmonk)

Quick testing with IEx console:

make console
# Your .env will be loaded automatically
# Then try:
config = Listmonk.Config.from_env()
{:ok, _} = Listmonk.new(config, :listmonk)
Listmonk.healthy?(:listmonk)
Listmonk.get_lists(:listmonk)

For detailed examples, see USAGE.md.

Documentation

Development

Using Make:

# See all available commands
make help

# Install dependencies
make install

# Run all checks (format, lint, test, dialyzer, compile)
make all

# Individual commands
make format        # Format code
make lint          # Run Credo linter
make test          # Run tests
make dialyzer      # Run Dialyzer static analysis
make compile       # Compile project
make console       # Start IEx console (loads .env if exists)
make docs          # Generate documentation
make clean         # Clean build artifacts

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! To ensure your contribution aligns with the project's direction, please follow these steps:

Open an issue first - Before submitting a Pull Request, please open an issue to discuss your proposed changes
Submit a PR - Once approved, feel free to submit a Pull Request

Quick links:

Acknowledgments

This library is based on the Python Listmonk client by Michael Kennedy. The Python implementation served as a reference for API coverage and functionality, adapted here to follow Elixir patterns and conventions.

Author

Andriyan Ivanov andriyan.ivanov@gmail.com / @mifkata