Choose Native APIs or Mac UI Automation

Published November 12, 2026 • Figment editorial team

If you are building an app that touches Apple data, you will hit the same fork early: use a documented protocol that Apple supports directly, or drive the macOS desktop layer with AppleScript, database polling, or private Objective-C. The right answer depends on the service. iMessage has no first-party REST API; Calendar does. Getting that wrong early costs weeks.

Two fundamentally different integration layers

Apple exposes two completely separate surfaces for third-party access.

The native API tier is built on documented, standards-based protocols: CalDAV for Calendar and Reminders, CardDAV for Contacts, and IMAP/SMTP for Mail. Apple's servers speak these protocols directly. Your app connects over HTTPS without needing a Mac at all.

The Mac UI automation tier covers everything else—chiefly iMessage, but also Notes, Shortcuts, and anything that lives only in a macOS app. Because Apple provides no public server-side API for these services, the only third-party path runs through the Messages app, its local SQLite database (chat.db), and either AppleScript or private framework injection. This tier lives on a Mac, not in a data center.

Conflating the two layers is the most common early design mistake. CalDAV is reliable and stateless. AppleScript combined with chat.db polling is stateful, brittle, and sensitive to OS updates.

The native API tier

For Mail, Calendar, and Contacts, Apple has a formal process: users authorize a third-party app through their Apple Account, and the app connects via standard protocols (Apple support: authorize third-party apps).

In practice this means:

Calendar — CalDAV at caldav.icloud.com, RFC 4791, HTTPS port 443.
Reminders — Also via CalDAV (VTODO components), same endpoint and authentication as Calendar.
Contacts — CardDAV, same authentication requirements.
Mail — IMAP at imap.mail.me.com (read) and SMTP at smtp.mail.me.com (send).

Third-party clients authenticate with an App-Specific Password (ASP): a reusable credential generated at account.apple.com that substitutes for the main Apple password in IMAP/SMTP/CalDAV/CardDAV clients (Apple support: App-Specific Passwords). Two-factor authentication must be active on the account. Each account holds up to 25 active ASPs, and all are revoked automatically when the Apple Account password changes.

Apple has a gated enrollment path for approved third-party apps at developer.apple.com/contact/request/icloud-oauth2, but it requires individual application and approval, and the page requires a Developer sign-in. Enrollment and approval terms must be verified independently before building on that path.

The native tier suits server-to-server automation well: it is stateless, runs from any server, and does not require a connected Mac. Its scope is limited to the services Apple has documented it for.

The Mac UI automation tier

iMessage, Notes, Shortcuts, and similar services have no Apple-documented server API. Every third-party integration reaches them through macOS itself.

The dominant pattern—used by projects such as BlueBubbles—combines AppleScript with chat.db polling. AppleScript handles sends and chat creation; a periodic read of the Messages SQLite database (~/Library/Messages/chat.db) detects incoming messages. For deeper functionality, BlueBubbles also offers an optional Private API bundle that uses native Objective-C to communicate directly with the Messages framework; this is a separate optional feature and does not apply to basic messaging.

This architecture has real constraints:

A running Mac is mandatory. The integration cannot move to Linux or a container without running macOS in a VM.
AppleScript is synchronous and slow. Burst operations or high-volume sends queue up and can slow the system.
chat.db reflects local sync state. If iCloud Message sync is behind, reads return incomplete history. A row appearing in chat.db is not proof of delivery.
Private framework injection breaks on major OS updates. Each macOS release can change private API signatures, requiring rapid patching.
System Integrity Protection and app sandboxing limit what a third-party process can read or inject, and these boundaries tighten with each release.

There is no Apple-documented first-party REST API for iMessage. The Mac automation tier is the only confirmed third-party path.

Supported interface hierarchy and failure-mode matrix

The table below maps each iCloud service to its access tier, the most common failure mode, and what a recovery path looks like.

Service	Access tier	Typical failure mode	Recovery path
Calendar	Native: CalDAV (RFC 4791)	App-Specific Password revoked on Apple Account password change	Generate a new ASP at account.apple.com; re-authorize
Reminders	Native: CalDAV (RFC 4791, VTODO)	App-Specific Password revoked on Apple Account password change	Generate a new ASP at account.apple.com; re-authorize
Contacts	Native: CardDAV	Same ASP revocation pattern	Same as Calendar
Mail	Native: IMAP / SMTP	IMAP connection dropped; SMTP auth rejected	Reconnect with valid ASP; check 2FA status
iMessage	Mac automation: AppleScript + chat.db	macOS update breaks AppleScript handler or optional private API bundle	Patch automation layer; validate against new OS version
iMessage	Mac automation: chat.db polling	Sync lag: local db behind iCloud; messages missing until sync catches up	Poll `historyComplete` flag; do not assume full history
Notes	Mac automation: AppleScript / native	Locked notes block reads	Prompt user to unlock; handle per-note error
Shortcuts	Mac automation: Shortcuts app	Action not installed on Mac (phone-only action)	Filter to Mac-compatible installed actions only
Photos	Mac sync: Photos library on Mac	Cloud-only asset not yet downloaded	Trigger download; wait for asset to be locally available
Drive	Mac sync: iCloud Drive daemon on Mac	File evicted or not yet synced locally	Request local copy; check sync status before reading
Find My	Mac automation (native support required)	Sharing settings revoked or location service off	Surface error; do not silently retry
Voice Memos	Mac automation: synced recordings	Recording still uploading from watch or phone	Poll sync state; treat partial sync as incomplete

Each row's failure mode is a real operational concern, not a theoretical one. Apps that treat the entire surface as a single reliable API will hit these in production.

Why the tier choice matters for your app

If your app only needs Calendar, Reminders, Contacts, or Mail, you can call CalDAV, CardDAV, or IMAP directly from any server. No Mac infrastructure, no AppleScript brittleness. Your team manages ASP rotation and reconnection when Apple Account passwords change.

If you need iMessage—or any service that lives only in macOS—you need a managed Mac. That means uptime responsibility, macOS version tracking, private-API patch cycles, and sync-lag handling. That operational surface grows with scale.

Figment Apple Connect focuses on the Mac automation tier. Its iMessage REST API lets your app send, search, and read messages through a hosted, signed-in Mac without building or operating that infrastructure yourself. iMessage access requires an approved Figment account and setup; live access depends on capacity and approval. The connection status reflects each service individually (connecting, needs_approval, syncing, ready, offline, reconnect_required, revoked), and non-ready services reject operations rather than returning stale data.

For Calendar, Contacts, and Reminders, Figment provides a synthetic read-only sandbox so you can build and test against the API shape. Live customer access to those services is not currently available through Figment. If you need live CalDAV or CardDAV access today, the native protocols described above remain the direct path your app handles independently.

Two scopes control iMessage access through Figment: messages:read for history and search, and messages:send for outbound messages. Both can be approved within a single app grant. Read access does not implicitly allow sending. For the full OAuth grant and REST endpoint reference, see OAuth for iCloud: Connect Apple Data to Your App.

Choosing your path

Connect directly to native-tier protocols if your app only touches Calendar, Reminders, Contacts, or Mail; your team is comfortable managing ASP rotation; and you do not need iMessage, Notes, or Shortcuts.

Use Figment Apple Connect if you need iMessage API access and want to avoid building and operating Mac infrastructure yourself, or if you want to test against Calendar, Contacts, or Reminders data while native live access is in development.

Both paths require a real Apple Account, real trusted-device approval, and careful sync-state management. Neither path bypasses Apple's permission model.

Developer access starts at $29/month per active live connection. Sandbox access is free and includes synthetic data so you can build against the API shape before going live. Access starts after setup—there is no immediate provisioning.

Figment.so