Skip to content
imessageapi

iMessage API documentation and developer reference

There is no Apple developer documentation for sending iMessages, so 'the docs' means each vendor's own. Here is what is consistent across all of them, what differs, and the reference shape you can build against before you have chosen one.

8 min readUpdated August 24, 2026Team

Searching for iMessage API documentation on developer.apple.com returns nothing usable, because Apple publishes no such API. What exists is eight or so vendors' own docs, and they are more alike than different.

The shape every provider shares

Learn this once and every vendor's documentation becomes skimmable.

ConcernNear-universal shapeWhere vendors differ
AuthAuthorization: Bearer <key>Some scope keys per line or per project
SendPOST /messages with to and textField names: text vs body vs message
AttachmentsA URL, or base64 in the same payloadSize limits and accepted types vary widely
InboundWebhook POST to your endpointSignature scheme, retry policy, ordering guarantees
Delivery eventsWebhook or a status field on the messageCoverage is genuinely uneven — check explicitly
Rate limits429 with Retry-AfterPublished limits are rare; discovering them empirically is normal
GroupsA conversation or chat idSupport ranges from full to absent

Build against your own types, not theirs

Because field names differ and vendors are young, define your own request and result types and map at the boundary. It costs one small file and makes a provider swap a contained change — see switching providers.

A reference interface to code against

The contract worth writing before you choose a vendor
export type Channel = "imessage" | "rcs" | "sms";
 
export type OutboundMessage = {
  to: string;                    // E.164, always
  text: string;
  attachments?: { url: string; contentType: string }[];
  /** Ordered preference. The layer below picks the first that will land. */
  prefer?: Channel[];
};
 
export type SendResult = {
  id: string;
  channel: Channel;
  status: "queued" | "sent" | "delivered" | "failed";
};
 
export type InboundMessage = {
  id: string;
  from: string;
  text: string;
  attachments: { id: string; contentType: string }[];
  receivedAt: string;            // RFC 3339
};
 
export interface MessagingProvider {
  send(message: OutboundMessage): Promise<SendResult>;
  /** Verify a webhook against the exact bytes received. */
  verifyWebhook(rawBody: string, headers: Headers): boolean;
  parseInbound(rawBody: string): InboundMessage | null;
}

The five things vendor docs under-explain

  1. Rate limits. Rarely published. Assume conservative, back off on 429, and treat throttling as the vendor protecting your line rather than an obstacle.
  2. Retry semantics on inbound. Delivery is at-least-once. Whether ordering is preserved is often unstated — do not assume it is.
  3. What happens for a non-iMessage recipient. Silent failure, automatic SMS fallback, or an explicit error? This changes your code substantially. Test it with a real Android number.
  4. Attachment limits. Size caps and accepted types are frequently discovered rather than documented.
  5. Number release on cancellation. Not an API question, but the one that determines whether you can leave. Ask before signing.

Where the real docs are

  • [Photon](/providers/photon-reviews) — public docs, open-source kits, an n8n node and a Vercel Chat SDK adapter. The most developer-legible in the category.
  • [Blooio](/providers/blooio-reviews) — public REST docs with an OpenAPI spec, and SDKs across Node, Python, Go and Java.
  • [LoopMessage](/providers/loopmessage-reviews) — public docs; check which capabilities are add-ons before you plan around them.
  • [Sendblue](/providers/sendblue-reviews) — public docs; the outbound capability you likely want sits on the enterprise tier.
  • [Linq](/providers/linq-reviews) — sandbox and docs available, generally through a sales conversation.
  • [BlueBubbles](/providers/bluebubbles-reviews) — open-source, self-hosted, and the docs are the source.

Language-specific implementations: Node.js, Python. For the plain HTTP view of all this, is there a third-party POST API; for testing before you commit, can I test in a sandbox.

Common questions

Where is the iMessage API documentation?
There is none from Apple. Each third-party provider publishes its own — Photon, Blooio, LoopMessage and Sendblue all have public docs; Linq's are gated behind a sales conversation.
Is there an iMessage API on GitHub?
Vendor SDKs and open-source bridges are on GitHub — BlueBubbles is the most established self-hosted server, and Photon publishes open-source client kits. There is no Apple-published repository.

Related

All 8 pages