# Use Hide My Email for Approved Agent Signups

Canonical: https://figment.so/blog/hide-my-email-agent-signups

When an agent signs up for a service on a user's behalf, it must not submit the user's real email. iCloud+ [Hide My Email](https://support.apple.com/en-gb/guide/mac-help/mchle62f7f45/mac) solves this: it generates unique, random forwarding aliases — one per service — that forward to any email address on the user's Apple Account. No public Figment endpoint and no Apple REST API manages these aliases programmatically. Creation, labeling, deactivation, and deletion happen through Apple's own surfaces: System Settings, iCloud.com, Safari, and Mail. The practical value for an agent workflow is the alias lifecycle design — label each address with agent context, track it in your own state store, and deactivate it cleanly when a subscription ends.

## The alias lifecycle

[Apple's Hide My Email](https://support.apple.com/en-gb/guide/mac-help/mchle62f7f45/mac) assigns a random address string. The agent never chooses the alias text. After creation, each alias carries two metadata fields:

- **Label** — displayed in System Settings and iCloud.com; use it to record the service, the agent identity, and the signup date.
- **Note** — free text; use it for workflow ID, subscription tier, or source context.

An alias moves through three stages:

| State | What it means | Reversible? |
|---|---|---|
| Active | Forwarding on; mail reaches the inbox | Yes — deactivate |
| Deactivated | Forwarding paused; address still reserved | Yes — reactivate |
| Deleted | Address gone; unrecoverable | No |

Deactivate when a subscription lapses. Delete only when the address will definitely never be used again. That discipline preserves re-subscription options without cluttering the user's alias list.

The **forwarding target** is independent of alias status. It points to any email address on the user's Apple Account — iCloud Mail or a personal domain address. Changing the forwarding target does not change the alias address or affect delivery until the next incoming message.

## Prerequisite: iCloud+ or Apple One

Hide My Email requires an active iCloud+ subscription, or an Apple One plan that includes iCloud+. Without a qualifying subscription, the feature does not appear in System Settings and no aliases exist to list or modify.

## Distinct from Sign In with Apple relay emails

When a user signs in to a third-party service using Sign In with Apple and chooses to hide their email, Apple creates a per-app relay address automatically. That relay is Apple-managed, generated per developer App ID, and separate from iCloud+ Hide My Email. The two do not share an alias list, management surface, or programmatic interface. This article covers iCloud+ Hide My Email for agent-managed signups outside of Sign In with Apple flows.

## Managing aliases through Apple surfaces

No public programmatic API — from Apple or from Figment — manages iCloud+ Hide My Email aliases. Creation, labeling, deactivation, and deletion happen through:

- **System Settings → [Your Name] → iCloud → Hide My Email** on macOS
- **iCloud.com → Hide My Email** in a browser
- **Safari and Mail** — these can generate a new alias automatically at signup forms

An agent workflow must prompt the user to create an alias before the signup, or draw from an alias the user has already created and recorded. The agent does not receive an alias address until the user provides it.

## Alias ledger design

Since aliases are managed through Apple's user interfaces, the agent's own state store becomes the tracking layer. Record every alias address the agent uses alongside the metadata needed to manage it later. A minimal ledger entry:

| Field | Example value | Purpose |
|---|---|---|
| `aliasAddress` | Apple-assigned random address | Submitted at signup |
| `label` | `"NewsletterApp · agent · 2026-11-12"` | Visible in Apple Settings |
| `note` | `"workflow:content-discovery · trial"` | User context |
| `state` | `active` | Lifecycle stage |
| `serviceUrl` | `https://example.com` | Maps alias to service |
| `createdAt` | `2026-11-12T10:00:00Z` | Audit |
| `deactivatedAt` | _(null until lapsed)_ | Cleanup trigger |

This is a developer-owned design. Store it in the same durable data store as the rest of the workflow state.

**Label discipline.** A label like `NewsletterApp · agent · 2026-11-12` lets the user identify the address in System Settings without opening the agent app. A generic label like `Alias 23` pushes cleanup burden back onto the user. Treat the label as a human-readable receipt.

**State drift.** If the user modifies or deactivates an alias manually in System Settings or iCloud.com, the agent's ledger entry will drift. Re-read the user's current alias state before acting on a lapsed subscription rather than assuming the ledger matches what Apple holds.

## Cleanup workflow

When an agent-managed subscription lapses, the cleanup sequence is:

1. **Subscription ends** → update local ledger to `deactivated`, record `deactivatedAt`, prompt the user to deactivate the alias in System Settings or iCloud.com.
2. **Confirmation window passes** (or the user confirms the relationship is closed) → prompt the user to delete the alias. Update ledger to `deleted`.
3. **Resubscription occurs before deletion** → prompt the user to reactivate the alias, update the label to the new signup date, resume using the address.

The agent prompts; the user acts. No alias operation modifies Apple account data without the user acting through Apple's interface.

---

## Related reading

- [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud) — the Figment connection model, OAuth flow, and token lifecycle that underpin every capability on this page.
- [Connect Find My Devices to an Assistant](/blog/find-my-device-integration) — a parallel pattern for exposing owned device locations to an approved agent.
- [Give an Agent Permission to Run Home Scenes](/blog/homekit-agent-controls) — the same connection model applied to HomeKit automation.
- [Use Shared Find My Locations in Approved Workflows](/blog/find-my-shared-location-workflows) — approved sharing patterns for location data.

[Connect Apple Account](/apple-connect/developers) to start building with the Figment iMessage API and synthetic sandbox. For Hide My Email, begin with the iCloud+ prerequisite and Apple Settings.