Skip to main content
Before you start
  • An Apple Account with two-factor authentication already on. App-specific passwords do not exist without it, and Postern cannot add one for you. If it is off, turn it on first — step 1 says where.
  • About 5 minutes, and your password manager open. Apple shows the password once, on a screen with no copy button, and cannot show it again.
  • Postern installed, with the Console open at http://127.0.0.1:8787. The Console answers only on the machine Postern runs on. That machine must reach the internet; behind a strict firewall, allow *.icloud.com and imap.mail.me.com:993 — the hosts iCloud needs. If Postern runs on another machine, open the Console from your own computer over SSH first: Open the Console over SSH.
  • Three connections, or none. One password creates mail, calendar and contacts together. You cannot connect only one, and all three are read-only.
1

Create an app-specific password at Apple

Sign in at account.apple.com/account/manage.In the left rail, select Sign-In & Security. Under the App-Specific Passwords card, select View details.A window opens, titled App-Specific Passwords. A line under the title counts the ones you already have. The heading Passwords sits over the list, one row each: the name you gave that password, and the date you made it. The list holds those two things only, never the password itself.
No App-Specific Passwords card? Two-factor authentication is off on the account. App-specific passwords do not exist without it, and Postern cannot turn it on for you. Turn it on first — on the web at account.apple.com, or in your Apple Account settings on an iPhone, iPad or Mac. Apple’s own help article calls the web control Upgrade Account Security; nobody here has seen that screen, so look for the wording your account shows. Come back here afterwards and the card is there.
Open your password manager before you go on.Press the + at the right-hand end of the Passwords heading.The Generate App-Specific Password window opens. It holds one field. Create below it is pale, and it does nothing while the field is empty.Type Postern into the field. The field carries no label. Its placeholder, e.g. Bill Pay, floats up into the corner as you type and becomes the label. The name only helps you find this password later in Apple’s list. Create turns solid.Press Create. The window dims and shows Updating….
Apple now stops you and asks for your Apple Account password. The flow has not broken.A window headed Confirm Your Password takes over. Under the heading it reads For your security, enter the password for: and then the address of your Apple Account. One field, placeholder Password. Two buttons, Cancel and Continue. Continue stays pale until the field has text.Type your Apple Account password here, not an app-specific password, and press Continue. This is Apple’s screen on Apple’s site. Postern never sees this password.
The Generate App-Specific Password window comes back, your name still in it, and shows Updating… again. Then Apple prints the password:
  • The heading reads Your app-specific password is:
  • Under it, the password itself: 4 groups of 4 lowercase letters, joined by hyphens — xxxx-xxxx-xxxx-xxxx.
  • Under that: Enter this password into the password field of the app you would like to sign in to. Password is case-sensitive.
  • One button, Done.
There is no copy control on this screen. No copy button, no copy icon, no link. Select the password text yourself and copy it by hand, hyphens included. Put it in your password manager now.Done is the only control on the screen, and it is one-way. Apple cannot show you this password again.
Press Done. You land back in the App-Specific Passwords window. The count under the title has gone up by one. A new row at the foot of the list carries the name you typed and today’s date.
Postern never asks for your Apple ID password. Everything on this step happens on Apple’s own site, so anything Apple asks you here goes to Apple, not to Postern.The Console’s own steps still name appleid.apple.com. Both addresses open the same account page today. Apple’s own instructions name account.apple.com, so this page does too.
2

Paste it into the Console

In the Console at http://127.0.0.1:8787, go to Sources → Add a source → iCloud. It is the first card under Paste a token.
Paste the app-specific password, never your Apple ID password. Postern stores whatever you paste and does not check it, and Apple then refuses it — why Postern cannot tell the two passwords apart.If you also plan to change your Apple ID password, change it first. An Apple ID password change revokes every app-specific password on the account, at once and without notice.
Fill the two boxes:
  • Apple ID — your @icloud.com mail address, even when you sign in to Apple with an address somewhere else. Mail accepts no other address. Calendar and contacts accept either one.
  • App-specific password — masked as you type.
Press Connect iCloud. The Console shows iCloud connected. and moves you to Sources, where one iCloud group now holds three connections.That message means Postern stored the password and created the three connections. It does not mean Apple accepted it. This step never contacts Apple. The first sync is the test.
Postern checks both boxes before it sends anything. An Apple ID that is not an email address gets That doesn’t look like an Apple ID — it should be an email like you@icloud.com. An empty password box gets Paste the app-specific password you generated — four groups of four. Postern never sees your Apple ID password, only this one. Both are Postern’s own refusals. Postern sent nothing. Correct it and press Connect iCloud again.
3

Watch the first sync land

In the Console, go to Sources → the iCloud group, and open the mail connection. It starts at Awaiting first sync. The first sync starts within about a minute. The label moves to Syncing… with a count that climbs, then to nothing at all.A healthy connection shows no status word. Stale, Unreachable, Error, Paused or Disconnected means a problem.On a large mailbox the first pass runs for minutes. Reload the page and watch the count under Envelopes cached climb.Sync now waits 30 seconds for the run to finish, then reports Synced — 0 updated. even when the run has not finished. On a first pass that means the sync is still at work, not that the mailbox is empty.Poll cadence, on each connection’s own page under Controls, sets how often Postern checks. The floor is 5 minutes — why these intervals.
Recency window sets mail to 3, 6 or 12 months. It appears on the mail connection’s page only — the calendar and contacts pages do not have it. Change it and Postern re-reads the whole window from the start, so Envelopes cached falls before it climbs again.
All three connections turn to Error. Mail shows icloud-mail: sync failed. Calendar and contacts show apple: DAV connect failed or apple: DAV account discovery failed. These messages name the stage, not the cause — Postern never logs what Apple said.The cause is nearly always the password: either it was wrong from the start, or Apple has revoked it. Three connections that stop on the same day after weeks of normal syncs is an Apple ID password change and nothing else.The Console disables Sync now while a connection sits in Error, with Syncing is held until the connection is restored beside it. Repair it at Apple instead. Make a new app-specific password — Create an app-specific password at Apple. Go to Sources → Add a source → iCloud, tick Yes — replace the stored app-specific password., and paste it. All three connections go back to active. It never creates a second copy.

​
Confirm it works

  • Sources holds one iCloud group with three connections: mail, calendar and contacts.
  • None of the three shows a status word.
  • Each shows a Last synced clock, a Next poll time, and a count under Envelopes cached, Events cached or Contacts cached. A zero count with a healthy clock is a real answer, not a failure — that connection has nothing inside the window it covers.

​
If something went wrong

​
What you have now

Three read-only connections behind one password: mail envelopes, calendar events and contacts. Any agent whose key carries mail, calendar or contacts can read them now, and can pull the body of a single message on demand. None can write: all three connectors ship with no actions at all, so no agent can send mail, change an event or edit a contact. You choose what an agent can read when you create its key, not here — a grant is one agent’s permission for one area of your life. You now carry one app-specific password at Apple. Apple allows up to 25 active app-specific passwords. The ⊖ on a row takes that one password back. Revoke all, below the list, takes back every one. Take this one back and Postern stops: the three connections fail their next sync, and nothing else on your Apple Account moves. An Apple ID password change does the same, with no warning. A disconnect in the Console stops all three at once and deletes the stored password. Either way, what Postern already cached stays as read-only history until you remove it separately.

​
Next

Connect Google and Gmail

your own Google Cloud app + one app password · about 20 minutes · weekly re-consent until you publish to production

Connect an agent

a key you have already created · a few minutes, plus a restart of the client · paste one config block