ListMonk API

Send newsletters via your self-hosted ListMonk instance using RelayAPI — cross-post social content to email subscribers.

Quick Reference

Before You Start

You need your ListMonk instance URL, admin username, and password.

Connect

curl -X POST https://api.relayapi.dev/v1/connect/listmonk \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_url": "https://listmonk.example.com",
    "username": "admin",
    "password": "your-password"
  }'

The connector canonicalizes the verified instance URL and stores it as the account's authoritative platform_account_id. Every publisher call derives its base URL from that immutable value, resolves only public destinations, rejects redirects, applies a 30-second through-body timeout, and limits the response to 512 KiB. Reconnect to change the instance; target_options and generic account metadata cannot redirect the stored Basic credential.

Send a Campaign

curl -X POST https://api.relayapi.dev/v1/posts \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Newsletter content...",
    "targets": ["acc_listmonk123"],
    "scheduled_at": "now",
    "target_options": {
      "listmonk": {
        "subject": "Weekly Digest",
        "list_id": 1,
        "template_id": 2
      }
    }
  }'

target_options Fields

Relay media attachments are not supported for Listmonk campaigns. Include provider-hosted images in content_html instead of sending a post media array.

Discovery

List your ListMonk lists and templates:

GET /v1/accounts/{id}/lists      # Returns ListMonk subscriber lists
GET /v1/accounts/{id}/templates  # Returns ListMonk email templates

Both discovery endpoints enforce the account's workspace boundary before contacting Listmonk and return 403 for an existing account outside the calling credential's grants. Provider JSON is bounded to 512 KiB.

Automations

Listmonk is self-hosted. The canonical instance base is the connected account's immutable provider identity, while the Basic credential is encrypted in RelayAPI's account-credential store. Public metadata is descriptive and cannot retarget the connection.

Send nodes (destination-only)

No inbound Listmonk triggers — use it as a downstream destination from other-platform triggers.