Listmonk

API key or basic auth to your Listmonk instance. Sosyabot acts as a service account, not a user — the same credentials serve every workspace user.

Authentication at a glance

Field	Value
Auth model	OAuth 2.0
Required ENV	LISTMONK_BASE_URL, LISTMONK_API_KEY, LISTMONK_USERNAME, LISTMONK_PASSWORD
Callback URL	${BASE_URL}(no callback — POST /api/v1/social/listmonk/connect with selected list IDs)
Scopes / permissions	Listmonk admin API: lists:read, campaigns:write
Auto token refresh	No — manual reconnect on expiry

ENV details

Provide either LISTMONK_API_KEY (preferred) or both LISTMONK_USERNAME + LISTMONK_PASSWORD. LISTMONK_BASE_URL is required and points at the Listmonk admin API root.

How to connect

1. Configure LISTMONK_* ENV (and restart ./service.sh if you changed .env).
2. Open Connections → Listmonk → Connect.
3. Pick one or more lists to publish to.

Token refresh

Static credentials. Rotate by updating ENV (or admin-panel override) and restarting the API process.

Notes

• Listmonk is a global integration shared by all workspace users — there is no per-user OAuth. Anyone in the workspace who connects a Listmonk channel reuses the configured credentials.
• The connect form lists available lists via GET /api/v1/social/listmonk/lists and lets you pick one or many. Channel ID is listmonk:<list-id-1>,<list-id-2>.
• Posting creates a campaign with content_type: html (default) and queues it via PUT /api/campaigns/<id>/status with status running.

Troubleshooting

If the channel shows needs_reconnect, the access token was rejected by Listmonk. Common causes:

• The user revoked Sosyabot's authorization on the platform.
• The platform invalidated the token (password change, security event).
• Your OAuth app credentials rotated and the existing tokens no longer match.

Re-run the connect flow above. See Troubleshooting for the workspace-wide checklist.

Related

Connections Overview

Composer

OAuth Callback URLs