> For the complete documentation index, see [llms.txt](https://puregamma-ai.gitbook.io/puregamma-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://puregamma-ai.gitbook.io/puregamma-ai/puregamma-ai/platform-and-architecture/relay-communication.md).

# Relay communication

## Why a relay exists

Apple does not provide a general server-side iMessage API. PureGamma therefore offers an optional, self-hosted macOS relay for users or deployments that choose iMessage delivery. The relay is not a cloud bypass and does not read the private Messages database.

## Message path

```mermaid
sequenceDiagram
  participant PG as PureGamma API
  participant R as Customer-managed Mac relay
  participant A as Apple Messages
  participant U as Verified recipient
  PG->>R: Signed HTTPS request + idempotency key
  R->>R: Validate timestamp and HMAC-SHA256
  R->>R: Persist delivery state
  R->>A: AppleScript sends message or media
  A-->>U: iMessage delivery
  R-->>PG: Delivery result
```

## Security contract

The API signs the raw request body using HMAC-SHA256 over `{timestamp}.{raw_body}`. The relay verifies the timestamp and signature before it accepts a delivery. An idempotency key lets the relay safely return the result of a prior attempt rather than duplicate a message.

The relay must be network-restricted, hold its shared secret outside source control, and run on a Mac signed into an account authorized to use Messages. The relay uses AppleScript to send; it does not access the Messages database. Voice media is converted on the relay to the expected iMessage voice-bubble format when applicable.

If the relay is offline, delivery fails transparently and the report remains in-product.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://puregamma-ai.gitbook.io/puregamma-ai/puregamma-ai/platform-and-architecture/relay-communication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.