Connect your accounts

The Accounts step (“Connect your accounts”) is where you give each source you turned on the private link or password it needs. It shows one card per source you enabled on the previous step — a source you left off doesn’t need an account and doesn’t appear here at all. Each card is its own small form with two buttons: a primary Save and test, and a plain Save beside it — there’s no single “save everything” submission, so filling in one source’s fields never risks resubmitting another’s, and you’re never forced to run a live check just to keep what you typed.

Save and test does both in one press, and never loses what you typed. A secret field (a password, a private link) is never shown back to you once it’s saved — only a note that a value is already stored (“Saved. Leave this blank to keep it.”), so leaving it blank on a later visit keeps whatever you already gave it rather than clearing it. If a check fails, whatever you saved stays saved — the field still reads “Saved. Leave this blank to keep it.” underneath the failure, never wiped back to empty, and a small note tells you to change what’s wrong and press Save and test again.

None of these connectors create a new person in your vault. If mail or calendar attendees don’t already match an existing person there, they’re written as plain text rather than linked — this is deliberate, so your vault never fills up with guessed or duplicate people behind your back.

Calendar: a private ICS link

Calendar connects with a private calendar subscription link (an .ics URL), not a username and password. Each major calendar service calls this something slightly different and keeps it in a different place:

• Google Calendar: open the calendar’s settings, and look for a “secret address” or private iCal link near the bottom of the settings for that specific calendar. It’s a long URL — copy the whole thing.
• iCloud: open the calendar’s sharing options and turn on “Public Calendar” to get a subscription URL. Despite the name “private,” this link works for anyone who has it — it’s not tied to who you originally gave it to and can be forwarded, so treat it exactly like a password. iCloud doesn’t offer a separate link that’s genuinely private to one recipient; its “Share Calendar” option invites a specific Apple account by email instead of producing an ICS URL at all, so it isn’t an alternative here.
• Outlook / Microsoft 365: open the calendar’s sharing or permissions settings and look for an ICS link under “publish a calendar” or “share calendar” — most Outlook variants offer a read-only ICS URL you can copy directly.

The Calendar card has exactly one field, Calendar address — paste the link in there and press Save and test. A webcal:// or webcals:// link works as-is; Maisnie rewrites either to https:// itself before ever fetching it, since “webcal” was never a different transport, only a hint to a calendar app. A plain https:// link also works as-is. Treat whatever you paste in like a password: anyone who has it can read your calendar’s contents (though not change it — it’s a one-way, read-only feed).

The check’s result reads in plain sentences: a working link says “Connected”, and names how many events it found (“Found N event(s) on your calendar.”, or “Your calendar has no events in it yet.” if there are none). A link Maisnie can’t reach reports “Maisnie could not reach your calendar at that address. Check that you copied the whole private address.”; something that answers but isn’t a readable calendar (a login page, an empty response) reports “That address did not return a calendar. Check that it is your calendar’s private address in iCal format.”; and leaving the field empty reports “Your calendar address is missing.” Any of these tells you to paste the address again and press Save and test.

Meeting times show in your own time zone, not the feed’s. Google and iCloud feeds usually carry their own time zone already; some Outlook and generated feeds instead publish events stamped only in UTC. Either way, Maisnie shows the time — and names the note’s own file — in your own time zone once it is set, converting a UTC-only event rather than leaving it in UTC. With no time zone set, both fall back to the clock on the computer running Maisnie, which matters most when that computer is not where you actually are (a cloud server pinned to UTC, for example).

Mail: an IMAP app password

Mail connects over IMAP, read-only — Maisnie asks your mail server for exactly that guarantee (EXAMINE, never SELECT, the command a mail client uses to open a mailbox without being able to mark anything read) rather than just promising not to misuse a fuller grant, and every connection negotiates TLS with certificate verification on, the same way a browser would; there is no plain, unencrypted fallback to ask for instead. Nothing on this connector can mark a message read, delete it, or send anything — there is no code path here that does any of the three.

The Mail card has four fields:

• Mail server — your provider’s own IMAP server address, for example imap.example.com; your provider lists it under its IMAP settings.
• Port (optional) — leave it blank to use the usual secure port, 993.
• Username — usually your full email address; check your provider’s own IMAP documentation if a plain username doesn’t work.
• App password — see below.

Two more settings this connector reads — which folder to sync (INBOX by default) and how many days back the very first sync looks (90 by default) — don’t have their own fields on this page yet; they use those defaults unless you edit config/majordomo.json directly, as tools.imap.settings.folder and tools.imap.settings.backfill_days.

For most providers, the password can’t be your normal account password — you’ll need an app password, a separate password generated specifically for one application, that you can revoke without changing your main password. Two caveats that catch people:

• Two-step verification is usually a prerequisite. Providers that support app passwords typically only offer them once two-step (or two-factor) verification is turned on for the account. If you don’t see an app-password option, check whether that’s the reason.
• A workspace or organization admin can block app passwords entirely, even when you’ve turned on two-step verification yourself. If app passwords don’t appear as an option at all, and you’re on a work or school account, that’s a setting an administrator controls, not something wrong with your own account.

Consult your provider’s own documentation for “app password” or “app-specific password” for the exact steps — they differ enough between providers that this guide doesn’t try to reproduce them.

Save and test’s result is one of a handful of plain sentences, chosen from what the check actually found rather than the raw error IMAP itself returned: a working login says “Connected” — “Maisnie signed in and can read your mail.”; a wrong username or password (including two-step not being on yet, or an admin block) reports “Your mail server did not accept the username and app password. Check both: an app password is not your usual password.” — one sentence covering all three, since IMAP’s own login failure doesn’t distinguish between them any more than that; a missing app password reports “Your app password is missing.”; a mail server name that can’t be found reports “Maisnie could not find a mail server with that name. Check the server name.”; one that doesn’t answer in time reports “Your mail server did not answer in time. Check the server name and port.”; and one that answers but won’t set up a secure connection reports “Maisnie reached your mail server but could not set up a secure connection. Check the port: most providers use 993.” Each of these tells you to fix the field it’s about and press Save and test again.

Feeds: no account needed

Feeds needs nothing but the URL of whatever RSS or Atom feed you want to follow — no password, no private link, nothing to authorize. Its one field, Feed addresses, takes one address per line. If a feed’s own URL carries a private token as part of the address, treat that URL the same as a secret — Maisnie stores it and shows it back on this page exactly as you typed it (the field’s own hint says so), since there’s nowhere else for a plain URL’s own authorization to live.

Press Save and test afterward. When every address you listed is reachable, it says “Connected” and names how many articles it found (“Found N article(s) in your feed.” for one address, or “…in your M feeds.” for several); if only some are reachable, it says “Partly connected” — “Read R of your M feeds and found N article(s).” plus a note to check the others, since each address has to be a feed, not a plain web page; with nothing listed yet it reports “There are no feed addresses yet.”; and if every listed feed failed, it reports “Maisnie could not read any of your feeds. Check that each address is a feed, not a web page.”

How often each one runs, and running one now

Once a source is enabled (the Sources step) and has whatever this page above asks for saved, it starts running on its own — there’s no separate “start syncing” switch beyond the two steps you’ve already done:

The very first run of each, right after maisnie up starts, happens within a few seconds rather than waiting out a full interval; after that it settles into its own schedule (with a small random offset per source, so several sources never end up waking on exactly the same tick forever). A run that fails backs off — doubling its wait each time, capped at 6 hours — until one succeeds, then returns to its normal interval.

To run a source right now instead of waiting for its schedule — right after saving a fresh password, or just to check something changed — run this from a terminal on the box itself:

maisnie run ical    # or: imap, feeds

This runs every one of that source’s jobs once and exits with the result (0 on a clean run). Unlike the scheduler’s own tick, an explicit run ignores whether you left the source turned off on the Sources step — you’re asking for it right now, not asking the scheduler whether it was due — but it still refuses a source that isn’t installed in this build at all.

maisnie pause stops the scheduler from starting any new connector run (a run already under way finishes normally, never cut off mid-sync); maisnie resume lets it start scheduling again. Both are safe to run any number of times — pausing an already-paused box, or resuming one that was never paused, is just the same request twice, not an error.

Next

Continue to choose a model.