Listmonk

A resource-oriented Ruby client for the listmonk HTTP API.

Installation

Add the gem to your bundle:

bundle add listmonk

The gem requires Ruby 3.3 or newer.

Configuration

Listmonk supports Basic authentication and its Authorization: token header. Basic authentication is the default:

client=Listmonk::Client.new(base_url: "https://newsletter.example.com",username: ENV.fetch("LISTMONK_USERNAME"),token: ENV.fetch("LISTMONK_TOKEN"))

Use token-header authentication when needed:

client=Listmonk.client(base_url: "https://newsletter.example.com/api",username: ENV.fetch("LISTMONK_USERNAME"),token: ENV.fetch("LISTMONK_TOKEN"),auth: :token,timeout: 30,open_timeout: 10)

The client accepts a server root or an URL ending in /api. Credentials may be omitted for public endpoints.

Usage

Every method returns a Listmonk::Response. Use data for the API payload, or inspect status, headers, and body when needed.

response=client.subscribers.list(page: 1,per_page: 50,list_id: [1,2])subscribers=response.data.fetch("results")subscriber=client.subscribers.create(email: "reader@example.com",name: "A Reader",lists: [1],attribs: {source: "website"}).dataclient.subscribers.update(subscriber.fetch("id"),name: "Reader")client.subscribers.send_optin(subscriber.fetch("id"))

Campaigns and transactional messages:

campaign=client.campaigns.create(name: "July news",subject: "What's new",lists: [1],from_email: "News <news@example.com>",content_type: "html",messenger: "email",type: "regular").dataclient.campaigns.create_content(campaign.fetch("id"),body: "<h1>Hello</h1>")client.campaigns.start(campaign.fetch("id"))client.transactional.deliver(template_id: 3,subscriber_email: "reader@example.com",data: {confirmation_url: "https://example.com/confirm"})

Subscriber imports and media uploads use multipart requests:

client.imports.create(file: "/tmp/subscribers.zip",params: {mode: "subscribe",subscription_status: "confirmed",lists: [1],overwrite: true})client.media.upload(file: "/tmp/banner.png",content_type: "image/png")

Resources cover all operations in the published Swagger collection:

• miscellaneous, settings, admin, and logs
• subscribers, lists, imports, and bounces
• campaigns, templates, media, and transactional
• maintenance and public

For an undocumented or newly added endpoint, use the low-level request method:

client.request(:get,"new-endpoint",params: {page: 1})client.request(:post,"new-endpoint",json: {enabled: true})

Errors

Non-successful responses raise typed exceptions. Every HTTP exception exposes status, body, and response.

beginclient.lists.retrieve(999)rescueListmonk::NotFoundError=>errorwarn"List not found: #{error.body.inspect}"rescueListmonk::RateLimitError# Retry with application-specific backoff.end

Connection failures raise Listmonk::ConnectionError, timeouts raise Listmonk::TimeoutError, and malformed JSON raises Listmonk::ParseError.

Development

Install dependencies and run the complete verification task:

bin/setup
bundle exec rake

RSpec uses WebMock for request-level tests and SimpleCov for coverage.

Docker integration tests

Run the opt-in integration suite against an ephemeral Listmonk 6.1.0 and PostgreSQL 17 environment:

bundle exec rake integration

The task starts Docker Compose on 127.0.0.1:19000, creates a temporary API user, runs live list, subscriber, template, authentication, and health checks, then removes the containers and database volume. Override the defaults with LISTMONK_PORT or LISTMONK_IMAGE.

Normal bundle exec rake runs only the WebMock suite and does not require Docker.

Releasing

Publishing uses RubyGems trusted publishing, so no long-lived RubyGems API key is stored in GitHub.

Before the first release, create a pending trusted publisher in your RubyGems.org profile with:

• Gem name: listmonk
• Repository owner: polydice
• Repository name: listmonk-ruby
• Workflow filename: release.yml
• Environment: release

To publish a version:

1. Update lib/listmonk/version.rb and CHANGELOG.md.
2. Run bundle exec rake, bundle exec rake integration, and bundle exec rbs validate.
3. Run bundle exec rake build and inspect the generated package under pkg/.
4. Commit the release and create a matching version tag, for example git tag v0.1.0.
5. Push main and the tag. The Publish gem GitHub workflow validates that the tag matches Listmonk::VERSION and publishes the gem.

License

The gem is available under the terms of the MIT License.