Listmonk API Setup

Unlike per-user OAuth integrations, Listmonk is a single shared service-account integration. Admins point Sosyabot at one Listmonk deployment and supply credentials; every workspace user who connects a Listmonk channel reuses those credentials.

End-user flow: Connections → Listmonk.

Overview

Form field	Options key	Required
Listmonk URL	listmonk_base-url	Yes
API Key (preferred)	listmonk_api-key	One of API Key OR username/password
Basic-auth username (fallback)	listmonk_username	Used if API Key is empty
Basic-auth password (fallback)	listmonk_password	Used if API Key is empty
Status	listmonk_integration_status	—

ENV fallback: LISTMONK_BASE_URL, LISTMONK_API_KEY, LISTMONK_USERNAME, LISTMONK_PASSWORD.

Step-by-step on your Listmonk deployment

1. Spin up Listmonk (if you haven't)

Listmonk is a self-hosted newsletter manager — see https://listmonk.app for install docs. Sosyabot supports Listmonk v3.0+ (API token model).

2. Generate an API token

In the Listmonk admin UI: Admin → Users → API tokens → New token.

• Name: e.g. "Sosyabot"
• User: pick or create a user with permissions to list view and campaign create + status update at minimum.
• Copy the generated token (Listmonk shows it once).

API token vs basic auth

The API token is preferred — it can be revoked individually and doesn't share a password with the human admin user. Basic auth (username/password) only exists as a fallback for older Listmonk versions and is ignored when API Key is set.

3. Confirm the public origin

Find the origin Sosyabot will hit — usually https://newsletter.example.com. No trailing slash. Sosyabot appends paths like /api/lists automatically.

Pasting into Sosyabot admin panel

/admin/api-integration/listmonk:

1. Listmonk URL: the public origin.
2. API Key: paste the API token (preferred).
3. (Skip username/password unless you're on Listmonk pre-v3.)
4. Status: Enable.
5. Save → Test connection button calls GET /api/lists and reports HTTP 200 / failure.

Failure messages mention Listmonk not configured: set LISTMONK_BASE_URL plus LISTMONK_USERNAME/PASSWORD or LISTMONK_API_KEY (or admin panel).

Verification

/app/channels → Connect → Listmonk. Sosyabot calls GET /api/v1/social/listmonk/lists and shows the available lists from your Listmonk deployment. The user picks one or many; the channel ID is listmonk:<list-id-1>,<list-id-2>.

Send a test campaign from /app/publishing and confirm it appears in Listmonk's Campaigns view with status running.

Troubleshooting

Symptom	Cause	Fix
Listmonk not configured: ...	Both admin and ENV missing required keys	Set Listmonk URL plus either API Key or username + password.
Test connection returns 401	Wrong API token / username / password	Re-issue the token in Listmonk; paste again.
Test connection returns 404	Wrong base URL — usually a trailing path or trailing slash	Use the bare origin (e.g. https://newsletter.example.com, no /admin, no trailing /).
Campaign created but never sent	Sosyabot creates with status: running — Listmonk handles delivery	Check Listmonk's own SMTP / SES configuration. Sosyabot only enqueues.

ENV fallback

LISTMONK_BASE_URL=https://newsletter.example.com
LISTMONK_API_KEY=<your token>
# OR (for pre-v3 Listmonk):
LISTMONK_USERNAME=<admin user>
LISTMONK_PASSWORD=<admin pass>

After editing .env run ./service.sh restart api.

Related

OAuth Credentials overview

Listmonk user-side connect

ENV Reference