iCloud Mail to Webhook

Why Route iCloud Mail Emails to a Webhook?

iCloud Mail is Apple's email service included with every Apple ID, used primarily by iPhone, iPad, and Mac users. While iCloud Mail is a capable email platform, its native tooling for programmatic automation was not built for developers who need structured, reliable data delivery to backend systems.

The native approach — iCloud IMAP (app-specific password) — introduces significant operational overhead. You need to manage credentials, poll or maintain persistent connections, and write custom parsing logic for every message field you care about. When your team is moving fast, that friction adds up to hours of maintenance per integration.

JsonHook eliminates that overhead by accepting inbound mail on your behalf and immediately firing a structured JSON payload to any HTTPS endpoint you specify. The email is parsed, attachments are base64-encoded, and headers are normalised — so your webhook handler can focus entirely on business logic rather than MIME parsing.

Below are the core benefits of routing your iCloud Mail messages through JsonHook instead of relying on the native alternative:

• Limitation avoided: Apple does not provide a public email API for iCloud Mail; there is no supported way to access iCloud messages programmatically beyond IMAP.
• Limitation avoided: iCloud IMAP access requires generating an app-specific password in Apple ID settings, and Apple may revoke access if unusual activity is detected.
• Limitation avoided: iCloud's forwarding rules are less flexible than Gmail's filter system — complex conditional logic is not supported.
• Zero-polling architecture: JsonHook pushes to your endpoint the moment mail arrives — no long-running background jobs needed.
• Automatic attachment handling: PDFs, images, and other file types are extracted, base64-encoded, and included in the JSON payload with their original MIME type.
• Retry with exponential back-off: If your endpoint is temporarily unavailable, JsonHook retries automatically — something the iCloud IMAP (app-specific password) does not do natively.
• Webhook signatures for security: Every delivery includes an HMAC-SHA256 signature header so you can verify the payload originated from JsonHook.

Whether you are building a support-ticket ingestion pipeline, a lead-capture workflow, or an automated document processor, JsonHook gives you a consistent, typed interface to iCloud Mail messages without the fragility of raw SMTP or polling-based API integrations.

How to Forward iCloud Mail to JsonHook

Getting iCloud Mail emails delivered to your webhook takes about five minutes. The process has two parts: creating a JsonHook address via the API, and configuring iCloud Mail to forward a copy of each incoming message to that address.

1. On a Mac or at iCloud.com, open Mail › Preferences (or Settings on iCloud.com) and select your iCloud account.
2. Navigate to the Rules or Forwarding section.
3. Add a forwarding rule that matches the desired messages and set the destination to your JsonHook inbound address.
4. On iCloud.com you can also go to Settings › Rules and create a rule with the action Forward to your JsonHook address. Note that iCloud requires you to verify the destination address first.

Once forwarding is active, every email that arrives in your iCloud Mail inbox (or matches your filter) will be relayed to your JsonHook address, parsed, and delivered to your endpoint as a JSON payload within seconds.

You can create your JsonHook inbound address with a single curl command. Replace YOUR_API_KEY with the key from your dashboard and set webhookUrl to your endpoint:

curl -X POST https://jsonhook.com/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "iCloud Mail inbound",
    "webhookUrl": "https://your-app.example.com/webhooks/email",
    "secret": "a-random-signing-secret"
  }'

The response includes your unique @in.jsonhook.com address. Copy that address and paste it into the forwarding field in your iCloud Mail settings. That is all the infrastructure you need to stand up.

iCloud Mail vs iCloud IMAP (app-specific password)

When developers first explore email-to-webhook automation they typically discover iCloud IMAP (app-specific password) — the official programmatic route provided by Apple. The table below shows how it compares to using JsonHook as an intermediary.

The native approach through iCloud IMAP (app-specific password) requires you to set up OAuth credentials or API keys, maintain a long-running listener or polling job, write your own MIME parser, and implement your own retry queue. Any one of those steps can become a reliability bottleneck in production.

JsonHook handles all of that infrastructure on your behalf. You get a single HTTPS webhook call with a predictable JSON schema every time a iCloud Mail email arrives — no polling, no credential rotation, no MIME parsing, and no bespoke retry code to maintain.

JSON Payload Example

When a iCloud Mail email is forwarded to your JsonHook address and delivered to your endpoint, the request body looks like the following. All fields are consistently present; optional fields such as htmlBody and attachments are included when the source message contains them.

{
  "id": "msg_01j8xkr4p2vn3q7w",
  "receivedAt": "2026-03-15T14:32:07.412Z",
  "from": {
    "name": "Alice Smith",
    "address": "[email protected]"
  },
  "to": [
    {
      "name": "",
      "address": "[email protected]"
    }
  ],
  "subject": "Your iCloud Mail message subject here",
  "textBody": "Plain-text content of the email body.",
  "htmlBody": "<div>HTML version of the email body.</div>",
  "headers": {
    "message-id": "<[email protected]>",
    "x-mailer": "Apple",
    "mime-version": "1.0"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 84234,
      "content": "JVBERi0xLjQK..."
    }
  ],
  "spf": "pass",
  "dkim": "pass"
}

The id field is a unique, stable identifier you can use for idempotent processing. The spf and dkim fields reflect the authentication results JsonHook observed when receiving the message, which you can use to enforce additional trust policies in your handler.

Attachment content is standard base64. Decode it with a single call in any language — Buffer.from(att.content, 'base64') in Node.js, base64.b64decode(att.content) in Python, and so on.

PHP handler for iCloud Mail messages forwarded through JsonHook:

<?php
$secret = getenv('JSONHOOK_SECRET');
$body = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_JSONHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Unauthorized');
}

$data = json_decode($body, true);
$from = $data['from']['address'];
$subject = $data['subject'];
error_log("iCloud Mail from $from: $subject");

http_response_code(200);
echo 'ok';

Common iCloud Mail to Webhook Use Cases

iCloud Mail is used by hundreds of millions of Apple device owners. It frequently receives order confirmations from the App Store, subscription alerts from Apple services, and personal correspondence from users deeply embedded in the Apple ecosystem. Webhooks let you automate workflows that would otherwise require manually watching an iCloud inbox.

• App Store receipt automation: Forward App Store purchase and subscription receipts from iCloud to a webhook that validates them against the Apple Receipt Validation API and updates subscription status in your database.
• Family sharing notifications: Apple's Family Sharing features send activity summaries and purchase approval requests via email. Intercept those with a webhook to build custom parental control dashboards.
• iCloud storage alert monitoring: Forward iCloud storage warning emails to a webhook that triggers automated cleanup scripts or sends mobile push notifications through a custom notification service.
• Personal automation hub: Power users who use iCloud Mail as their primary inbox can forward specific sender or subject filters to JsonHook and build custom automation flows — calendar events, home-automation triggers, or smart-home routines — that Apple Shortcuts alone cannot achieve.