Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect listmonk to Fondoo

Live6 min readUpdated

listmonk is a self-hosted newsletter and mailing list manager. Connecting it lets Fondoo send newsletters to one of your listmonk lists. Your AI agent drafts each issue, and nothing goes out until it is approved and scheduled.

What Fondoo can do with it

Fondoo treats listmonk as a publishing channel, next to your social networks. Sending goes through Upload-Post, the posting partner Fondoo uses for these channels. Upload-Post logs in to your listmonk instance, then creates and sends a campaign to the list you chose (Upload-Post's listmonk page).

With listmonk connected, your agent can:

  • Draft newsletter issues, either written for you (draft_social_posts) or from text you supply (save_social_draft).
  • Schedule approved issues within your posting rules (schedule_social_posts) and show them on your calendar (get_social_calendar).
  • Cancel a scheduled issue before it is sent (cancel_post).

What each issue must have:

  • Text only, up to 200,000 characters. No image or video attachments.
  • A subject line in listmonk_title, 3 to 500 characters. It becomes the email subject.
  • consentConfirmed set to true. This is your confirmation that everyone on the list agreed to get your emails. Fondoo refuses to schedule an issue without it.

Fondoo cannot recall an email after it is sent, and it does not collect open or click stats for listmonk. Use listmonk's own campaign reports for that.

Needs your approval: by default, every issue waits in your approval queue before it is scheduled. Once approved and due, it is sent to the whole list with no second check, so read it carefully. Saving credentials (configure_upload_post_platform) and changing posting rules (update_distribution_rules) are owner-only steps.

Before you start

  • A running listmonk instance that you administer. Its web address must be reachable over the internet, because Upload-Post's servers connect to it. Use HTTPS.
  • A list of people who agreed to hear from you. A double opt-in list is safest. listmonk sends campaigns on a double opt-in list only to confirmed subscribers (listmonk docs). On a single opt-in list, unconfirmed subscribers get emails too.
  • Working email sending in listmonk (an SMTP server set up in listmonk's settings). Your email provider may charge for sending. listmonk itself is free and open source.
  • You are the owner of your Fondoo workspace, with an owner API key for one REST call (see below).

Dashboard note: the Available list on Fondoo's Connections page does not show listmonk today. Set it up through your agent and one REST call, as described below. Once connected, listmonk appears in the Connected card.

Step by step: get your credentials

Fondoo needs four values. Each goes into a field with the same name in Fondoo:

ValueFondoo field
Your instance address, for example https://lists.example.cominstance_url
A listmonk user nameusername
That user's secret (see step 3)password
The ID of the list to send tolist_id
  1. Create a role with only the access Fondoo needs. In listmonk, open Admin → Users → User roles. Create a user role that can view, manage and send campaigns (campaigns:get, campaigns:manage, campaigns:send). Then create a list role that gives that role access to just the list you will use. campaigns:send is separate from the manage permissions, and listmonk needs it to start a campaign (listmonk roles). Upload-Post does not publish the exact permissions it uses, so this may differ for your account.
  2. Create an API user. Under Admin → Users, add a new user and choose the API user type (labels may differ by version). Give it the roles from step 1. listmonk creates a secret token for API users instead of a password (listmonk API docs). Copy the token when it is shown.
  3. Decide what goes in password. Put the API user's name in username and its token in password. Upload-Post's listmonk page describes this setup (an API user and token over HTTP Basic). Another Upload-Post page mentions your regular username and password instead. Recent listmonk versions document API access only through API users, so try the API user first. If that fails, check with Fondoo support before using a personal login. This may differ for your account.
  4. Find the list ID. Open Lists in listmonk. The lists page shows each list's numeric ID. Copy the ID of your opted-in list.

Connect it in Fondoo

To get the setup steps as a link, your agent can call connect_service({provider:"listmonk", siteId}) (REST: POST /v1/ops/connect_service). It returns a signed link, valid for 15 minutes, plus a QR code and these setup steps. That link only shows instructions. Your listmonk details are saved with configure_upload_post_platform, below.

(a) Ask your agent, then save the credentials yourself

Example prompt:

Set up listmonk newsletters for my site. Create the Upload-Post connection for listmonk and give me the connectionId. I'll add the credentials myself.

  1. The agent calls connect_social with { "siteId": "<site>", "provider": "upload_post", "network": "listmonk", "redirectUrl": "https://..." }. It returns a connectionId. If you already linked other networks through Upload-Post for this site, you can reuse that connectionId.
  2. You save the credentials with configure_upload_post_platform. This is an owner-only call and there is no secure paste form for it. Run it yourself with REST, so your secrets never appear in agent chat:
curl -X POST https://api.getfondoo.com/v1/ops/configure_upload_post_platform \
  -H "Authorization: Bearer $FONDOO_OWNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR_SITE_ID","connectionId":"YOUR_CONNECTION_ID","network":"listmonk","credential":{"instance_url":"https://lists.example.com","username":"fondoo-api","password":"API_TOKEN","list_id":"3"}}'

All four values must be text, so put the list ID in quotes. A successful reply includes "connected": true. Fondoo rejects owner API keys if your workspace requires owner two-factor authentication. In that case, an agent signed in as you (the owner) through OAuth can make the call, but the secrets then stay in that chat's history.

  1. The agent calls refresh_social_accounts with { "siteId": "<site>", "connectionId": "<id>" }.
  2. Add listmonk to your posting rules with update_distribution_rules, for example { "network": "listmonk", "formats": ["text"] }. Only a signed-in human owner can do this. The call replaces all your rules, so run get_distribution_rules first and keep your other networks. If you leave out the other settings, Fondoo allows one issue per day between 09:00 and 17:00 UTC, and each one needs approval.

(b) In the dashboard

After setup, open Connections. listmonk shows in the Connected card. Its Reconnect button only gives you a fresh setup link and these steps. It does not change your credentials.

Test that it works

  1. Ask your agent to run list_social_accounts. You should see an account with network listmonk.
  2. Make a small test list in listmonk that contains only your own confirmed address. Connect that list ID first.
  3. Ask the agent to save a short test issue with save_social_draft. Include "details": { "listmonk_title": "Test issue", "consentConfirmed": true }. Then schedule it with schedule_social_posts and approve it.
  4. Check your inbox and listmonk's Campaigns page. When you are happy, save the credentials again with your real list_id.

Troubleshooting

  • "listmonk requires listmonk_title" or "listmonk requires consentConfirmed." Add both to the issue's details. Only set consentConfirmed if your list really is opted in.
  • "listmonk: invalid title." The subject must be 3 to 500 characters.
  • "Invalid platform credentials." All four fields must be non-empty text, with no extra fields. Write list_id as "3", not 3.
  • The issue fails at send time. Upload-Post could not log in or send. Check that your instance is reachable from the internet over HTTPS. Check that the API user is active and has campaign and send permissions on that list. Then save the credentials again with configure_upload_post_platform.
  • Some subscribers did not get the email. On double opt-in lists, listmonk sends only to confirmed subscribers. Unsubscribed people never get campaigns. This is expected.
  • "Enabled network not found" when scheduling. listmonk is not in your posting rules yet. Add it with update_distribution_rules.

Limits, data and security

  • Rate limits: listmonk's API docs list HTTP 429 for too many requests but give no fixed number. How fast emails go out depends on your listmonk settings and your email provider's limits. Upload-Post does not publish a daily cap for listmonk. Your Fondoo posting rules set the daily number of issues.
  • Consent: only send to people who opted in. Your subscribers, unsubscribes and bounces stay in listmonk. Fondoo does not copy your subscriber list.
  • What Fondoo stores: Fondoo passes your credentials to Upload-Post and never sends them back to you or your agent. Fondoo keeps the account name, network and your issues.
  • Rotate: in listmonk, create a new API user with the same roles, or reset the token if your version offers that. Save the new values with configure_upload_post_platform, then delete the old user.
  • Disconnect: disable or delete the API user in listmonk under Admin → Users. Then take listmonk out of your posting rules with update_distribution_rules. Disabling the user in listmonk is what actually stops access.