@roucoule/send

Open-source CLI and library to send Roucoule emails via your own SMTP server.

Roucoule itself is a closed-source SaaS, but this client is open: it handles your SMTP credentials, so you can audit exactly what happens to them. They never leave your machine.

Why this exists

Roucoule never sees your SMTP credentials. This package keeps them on your machine and sends emails directly to your SMTP server, using the Roucoule API only to fetch article content and report delivery results.

Installation

Node (npm)

npm install -g @roucoule/send
# or one-off:
npx @roucoule/send --feed-id feed_xxx art_yyy

Deno (JSR)

deno install -gA jsr:@roucoule/send

Both expose the same roucoule-send command.

Quick start

# First run: interactive wizard for SMTP + API token.
# Saved to ~/.config/roucoule/config.json (mode 0600).
roucoule-send

# Send an article (prepare it as "ready to send" in the Roucoule UI first).
roucoule-send --feed-id feed_xxx art_yyy

# Dry run.
roucoule-send --feed-id feed_xxx --dry-run art_yyy

Run roucoule-send --help for full options.

--limit and --filter deliberately do not report back to Roucoule. Reporting a subset marks the whole article as sent, and Roucoule then refuses to serve it to the recipients left out. Pass --mark-sent if that is really what you want.

Programmatic use

// Node:
import { createApiClient, createNodemailerSender, send } from "@roucoule/send";

// Deno:
// import { ... } from "jsr:@roucoule/send";

const api = createApiClient("https://roucoule.dev", "rcl_…");
const sender = createNodemailerSender({
  host: "mail.example.com",
  port: 465,
  username: "[email protected]",
  password: "…",
});

const result = await send({ api, sender }, "feed_xxx", "art_yyy");
console.log(`Sent ${result.sent}, failed ${result.failed}`);

GitHub Action

See examples/github-action.yml.

What leaves your machine

The promise of this package is that Roucoule never holds your SMTP credentials. Here is exactly what does and does not travel, so you can check the claim rather than take it on faith.

| Data | Goes to Roucoule? | | ----------------------------------- | ------------------------------------------------------------------- | | SMTP host, port, username, password | Never. Stored in ~/.config/roucoule/config.json, mode 0600. | | Your API token | Yes — as a bearer token, it is how the API knows you. | | Subscriber ids and delivery status | Yes. That is the point of mark-sent. | | SMTP error messages | Codes only by default (550 5.1.1). See below. | | Email bodies | No. Roucoule rendered them; it already has them. |

An SMTP rejection routinely names your relay, its internal hostname or its IP address. --report-errors decides how much of it is reported back:

roucoule-send --report-errors redacted …  # default: "550 5.1.1"
roucoule-send --report-errors full …      # the server's full message
roucoule-send --report-errors none …      # the failed status, nothing else

You always see the full message locally, whichever mode you pick.

To watch the traffic yourself, --audit prints every HTTP call made to Roucoule — method, URL, body sizes, timings, bearer token redacted:

roucoule-send --audit --feed-id feed_xxx art_yyy
→ GET https://roucoule.dev/api/v1/feeds/feed_xxx/articles/art_yyy/package — 200 ↓48213B in 214ms

Deliverability

Your From: domain needs SPF, DKIM and DMARC, whatever you send with. doctor checks all three, verifies your SMTP credentials without sending anything, and prints the DNS record to add when one is missing:

roucoule-send doctor --from [email protected]
✓ Config: API https://roucoule.dev, SMTP mail.example.com:465
✓ SMTP: Connected and authenticated.
✓ SPF: v=spf1 include:_spf.example.net ~all
✓ DKIM: Key published for selector default.
! DMARC: DMARC on example.com is p=none: monitoring only, nothing enforced.
    → Move to p=quarantine once your reports show only legitimate senders.

Before the real send

# See the recipient list and anything that looks off, without sending.
roucoule-send --dry-run --feed-id feed_xxx art_yyy

# Render one subscriber's email to a local file and open it.
roucoule-send preview --feed-id feed_xxx --open art_yyy

# Send one rehearsal email to yourself, with real content.
roucoule-send --test-to [email protected] --feed-id feed_xxx art_yyy

If a run is interrupted

Every delivery is written to a journal under $XDG_STATE_HOME/roucoule/runs as it happens. A crash, a Ctrl-C or a failed mark-sent leaves that journal behind, and the next run refuses to start blind:

roucoule-send --feed-id feed_xxx art_yyy
An interrupted run for art_yyy is on record: 412 of 418 attempted recipients
were delivered, and the results were never reported.
Re-run with --resume to continue it, or --restart to discard it.

--resume picks up where it stopped, skipping everyone already delivered, and reports the complete result set. Nobody gets the email twice.

License

MIT. See LICENSE.

Contributing

Bug reports and small PRs welcome. This package is intentionally minimal — a thin client over the Roucoule API. Feature requests are better directed to the Roucoule service itself.