Calendar and contacts
How calendars and contacts are discovered and synced, and what you can do with them in the app and from the CLI.
Calendars and contacts come from the same accounts as your mail. There is nothing extra to set up: when you add an account, the engine looks for its calendar and address book servers and starts syncing them a few seconds after mail.
Which accounts have them
| Account | Calendars | Contacts |
|---|---|---|
| Gmail and Google Workspace | CalDAV (Google’s endpoint) | Google People API, including contact groups |
| iCloud, Yahoo, FastMail, GMX, Posteo, mailbox.org, Yandex, Zoho | CalDAV | CardDAV |
| Any other IMAP account | CalDAV, if the provider publishes it | CardDAV, if the provider publishes it |
| Microsoft 365, Outlook.com | Not available (no CalDAV) | Not available (no CardDAV) |
If a provider offers neither service, that account simply has no calendars or contacts in Airpost. Its mail is unaffected. Contacts you’ve emailed still show up as Found in Mail suggestions.
How servers are found
For non-Google accounts, the engine follows RFC 6764 service discovery:
The TLS records (_caldavs, _carddavs) are tried first, and a TXT record’s path is honoured when present. The built-in table covers providers that don’t publish SRV records:
| Provider | CalDAV host | CardDAV host |
|---|---|---|
| iCloud | caldav.icloud.com | contacts.icloud.com |
| Yahoo | caldav.calendar.yahoo.com | carddav.address.yahoo.com |
| FastMail | caldav.fastmail.com | carddav.fastmail.com |
| GMX | caldav.gmx.net | carddav.gmx.net |
| Posteo | posteo.de | posteo.de |
| mailbox.org | dav.mailbox.org | dav.mailbox.org |
| Yandex | caldav.yandex.ru | carddav.yandex.ru |
| Zoho | calendar.zoho.com | contacts.zoho.com |
DAV uses the same credentials as the account’s IMAP login, so an app password for iCloud or FastMail must allow calendar and contacts access too.
If your server isn’t found automatically, the engine reads AIRPOST_ENGINE_CALDAV_HOST and AIRPOST_ENGINE_CARDDAV_HOST (a host, optionally with a port) as overrides. These are engine environment variables, so they apply to every account the engine runs.
How often they sync
Calendars and contacts run on their own worker per account, separate from mail, on a fixed schedule:
| What | When |
|---|---|
| First pass | 15 seconds after the account starts, so mail gets a head start |
| Calendars | Every 15 minutes |
| Contacts | On the first pass, then every 75 minutes |
| After Google’s daily API quota is hit | Paused for 4 hours |
| After an error a retry won’t fix | Paused for 90 minutes |
| After a temporary error | Retried on the next 15-minute pass |
| After a 401/403 or revoked sign-in | Stops until you reconnect the account |
Calendar and contact errors never put the account into an error state or stop mail. The fixed cadence ignores manual mail refreshes on purpose: syncing contacts on every refresh used to exhaust Google’s quotas within hours.
Changes you make (a new event, an edited contact) are sent to the server right away as tasks, not on the next pass. To pull from the server now, use Refresh calendars (Cmd+Shift+R / Ctrl+Shift+R) or:
airpost calendar sync
Calendar
Open the calendar with Window > Calendar, or with these keys:
| Action | macOS | Linux |
|---|---|---|
| Go to Calendar | Cmd+Alt+2 | Ctrl+Shift+2 |
| Go back to Mail | Cmd+Alt+1 or Cmd+0 | Ctrl+Shift+1 or Ctrl+0 |
| Go to today | Cmd+T | Ctrl+T |
| Next / previous period | Cmd+Right / Cmd+Left | Ctrl+Right / Ctrl+Left |
| Refresh calendars | Cmd+Shift+R | Ctrl+Shift+R |
You can view your calendars by day, week, month or as an agenda.
Create and edit events
Click New Event. You can type something like “Coffee next Monday at 9AM” and Airpost fills in the date and time. Add invitees, a location or video call, alerts and a repeat rule.
With an event selected, the arrow keys move it and Shift with the arrow keys resizes it. Read-only calendars (shared calendars you can’t write to, subscribed holiday calendars) can’t be edited, and new events can’t be created in them.
Edits to a repeating event can apply to a single occurrence or to the whole series; the CLI also offers “this and following” (--scope following). Repeating events are expanded locally, so every occurrence shows without asking the server.
Invitations
Invitations in your mail show the event with Accept, Maybe and Decline. Answering updates the event and mails your reply to the organizer. Propose New Time… sends the organizer a counter-proposal instead.
From the CLI
airpost calendars # ids, accounts, names, read-only flag
airpost calendar list --from tomorrow --to 7d # every occurrence in the range
airpost calendar create --calendar <id> --title "Design review" \
--start "2026-11-20 14:00" --end "2026-11-20 15:00" \
--guest ana@example.com,li@example.com --location "Room 3"
airpost calendar create --calendar <id> --title "Standup" \
--start "2026-11-17 09:30" --repeat "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
airpost calendar update <event-id> --scope this --occurrence "2026-11-19 09:30" --delete
airpost calendar rsvp <event-id> accepted --comment "See you there"
airpost calendar rsvp <event-id> tentative \
--propose-start "2026-11-20 16:00" --propose-end "2026-11-20 17:00"
--end defaults to an hour after --start (a day with --all-day). Times accept relative values (30m, 2h, 3d, tomorrow), a date, or a date and time. --scope is this, following or all (the default). With guests, the event is organised by the account and the server sends the invitations where it supports that.
AI agents can do the same through the MCP server.
Contacts
Open contacts with Window > Contacts, or Manage contacts on an account in Preferences > Accounts.
- Create, edit and delete contacts. Changes go to the account’s address book on the server.
- Found in Mail lists people you’ve exchanged mail with who aren’t in an address book. Add any of them with one click.
- Import vCards by dragging
.vcffiles in, or with Import vCards…. Export selected contacts as a.vcffile. - On Google accounts, contact groups (labels in Google Contacts) sync both ways.
From the CLI:
airpost contacts ana # contacts whose name or address starts with "ana"
airpost contact get <contact-id> --json
airpost contact create --name "Ana Souza" --email ana@example.com --company "Example"
airpost contact update <contact-id> --phone "+1 555 0100"
airpost contact import ~/Downloads/team.vcf # or - for stdin
airpost contact export <id1> <id2> > picked.vcf
contact update replaces only the fields you pass. For fields without a flag, pass --patch with JSON in the shape contact get --json prints under data.
Autocomplete in the composer draws from both your address books and the addresses in your mail, all searched locally.
Edge cases
- Read-only calendars stay read-only everywhere, including the CLI and MCP:
calendar createrejects them. - Deleted on the server. Contacts or events deleted elsewhere disappear on the next pass. For Google, deletions arrive as tombstones and remove the local copy.
- Multiple accounts. Each account’s calendars and address books are separate. Give
--accountto CLI commands when more than one account could apply. - No calendar for an account after adding it: wait for the first pass (about 15 seconds), then check
airpost logs <account>for discovery messages.