> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpostern.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect iCloud
> One app-specific password from Apple gives Postern three read-only connections: mail, calendar and contacts.
**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](#app-password) 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](/reference/ports#what-postern-connects-out-to). If Postern runs on another
machine, open the Console from your own computer over SSH first:
[Open the Console over SSH](/start/remote-access#ssh-tunnel).
* **Three connections, or none.** One password creates mail, calendar and
contacts together. You cannot connect only one, and all three are read-only.
Sign in at
[account.apple.com/account/manage](https://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](https://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.
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](/reference/provider-sign-ins#three-credentials-that-behave-like-passwords).
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.
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.
| Connection | What it collects | Checked every |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Mail | Who sent it, the subject, the dates and the flags, from **INBOX** and **Sent** only. Postern never stores the message text — an agent that asks for one message pulls it from Apple on demand. Reaches back 180 days. | 10 minutes |
| Calendar | Every calendar on the account. Postern stores every date of an event that repeats as its own row, from 90 days back to about 400 days ahead. It does not store a date further out until that event next changes. | 15 minutes |
| Contacts | Every address book. | 15 minutes |
**Poll cadence**, on each connection's own page under **Controls**, sets how often
Postern checks. The floor is 5 minutes —
[why these intervals](/reference/mcp-freshness#what-the-cache-holds-by-source).
**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](#app-password). 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 see | What to do |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No **App-Specific Passwords** card under **Sign-In & Security** | Two-factor authentication is off on the account. Turn it on at `account.apple.com`, or in your Apple Account settings on an iPhone, iPad or Mac — [Create an app-specific password at Apple](#app-password). |
| **Confirm Your Password** appears after you press **Create** | Apple wants your Apple Account password, not an app-specific one. Type it and press **Continue**. The flow carries on where it stopped — [Create an app-specific password at Apple](#app-password). |
| No copy button on the screen that shows the password | Apple does not put one there. Select the password text yourself and copy it by hand, hyphens included — [Create an app-specific password at Apple](#app-password). |
| You closed Apple's screen before you copied the password | Apple cannot show it again. Make a second one and paste that. Take the lost one out of Apple's list with the **⊖** on its row — [Create an app-specific password at Apple](#app-password). |
| Mail stays empty while calendar and contacts fill up | The **Apple ID** box holds an address that is not `@icloud.com`. Mail accepts your `@icloud.com` address only. Paste again with that address — [Paste it into the Console](#paste). |
| `icloud-mail: sync failed`, `apple: DAV connect failed`, or `apple: DAV account discovery failed` | The password is wrong, or Apple revoked it. Make a new one, then re-paste it with **Yes — replace the stored app-specific password.** ticked — [Watch the first sync land](#first-sync). |
| `Synced — 0 updated.` on a mailbox that is not empty | The sync has not finished. Reload the connection's page and watch **Envelopes cached** climb — [Watch the first sync land](#first-sync). |
## 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](/reference/grants-and-sectors#what-a-grant-covers).
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
your own Google Cloud app + one app password · about 20 minutes · weekly
re-consent until you publish to production
a key you have already created · a few minutes, plus a restart of the client ·
paste one config block