Airpost
Accounts

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

AccountCalendarsContacts
Gmail and Google WorkspaceCalDAV (Google’s endpoint)Google People API, including contact groups
iCloud, Yahoo, FastMail, GMX, Posteo, mailbox.org, Yandex, ZohoCalDAVCardDAV
Any other IMAP accountCalDAV, if the provider publishes itCardDAV, if the provider publishes it
Microsoft 365, Outlook.comNot 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:

ProviderCalDAV hostCardDAV host
iCloudcaldav.icloud.comcontacts.icloud.com
Yahoocaldav.calendar.yahoo.comcarddav.address.yahoo.com
FastMailcaldav.fastmail.comcarddav.fastmail.com
GMXcaldav.gmx.netcarddav.gmx.net
Posteoposteo.deposteo.de
mailbox.orgdav.mailbox.orgdav.mailbox.org
Yandexcaldav.yandex.rucarddav.yandex.ru
Zohocalendar.zoho.comcontacts.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:

WhatWhen
First pass15 seconds after the account starts, so mail gets a head start
CalendarsEvery 15 minutes
ContactsOn the first pass, then every 75 minutes
After Google’s daily API quota is hitPaused for 4 hours
After an error a retry won’t fixPaused for 90 minutes
After a temporary errorRetried on the next 15-minute pass
After a 401/403 or revoked sign-inStops 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:

ActionmacOSLinux
Go to CalendarCmd+Alt+2Ctrl+Shift+2
Go back to MailCmd+Alt+1 or Cmd+0Ctrl+Shift+1 or Ctrl+0
Go to todayCmd+TCtrl+T
Next / previous periodCmd+Right / Cmd+LeftCtrl+Right / Ctrl+Left
Refresh calendarsCmd+Shift+RCtrl+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 .vcf files in, or with Import vCards…. Export selected contacts as a .vcf file.
  • 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 create rejects 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 --account to 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.