email-webhook-receiver/README.md

📬 Email Webhook Receiver for ForwardEmail.net

This is a simple PHP webhook endpoint designed to receive incoming emails from ForwardEmail.net. The script stores the raw email (.eml) files in a structured folder hierarchy and optionally triggers processing scripts per sender.

---

🚀 Features

• Accepts HTTP POST requests with raw email JSON data.
• Saves each email in a structured folder:
  data/emails/<sender-domain>/<sender-local>/
• Supports custom automation per sender:
  Automatically runs index.sh or index.php in the sender's folder if they exist.
• CLI-compatible for testing/debugging.

---

📁 Folder Structure

data/  
└── emails/  
  └── example.com/  
    └── alice/  
    ├── 65ef123e4c1a0.eml  
    ├── index.php     # optional  
    └── index.sh      # optional  

---

⚙️ Installation

1. Clone this repository:

   git clone https://github.com/yourusername/email-webhook-receiver.git
   cd email-webhook-receiver

2. Make sure data/emails/ is writable by your web server:

mkdir -p data/emails
chmod -R 775 data/emails

3. Configure your web server (e.g., Apache or Nginx + PHP) to POST email data to this script.

⸻

📨 Using with ForwardEmail.net

In your ForwardEmail account settings, set the Webhook URL to this script:

https://yourdomain.com/path/to/index.php

Make sure your server is publicly accessible and uses HTTPS.

ForwardEmail will send JSON payloads like:

{
  "raw": "Full raw email as string...",
  "from": {
    "value": [
      {
        "address": "alice@example.com"
      }
    ]
  }
}

⸻

🧪 Local CLI Testing

You can test the webhook manually via CLI:

php index.php < sample.json

Where sample.json contains a raw test email in JSON format (in ForwardEmail.net format).

⸻

🛠️ [Optional] AUTO-PROCESSING emails (per-sender)

To auto-process incoming emails, create either:
• index.sh: a shell script that reads from stdin
• index.php: a PHP script that reads from stdin

These will be triggered automatically upon email arrival.

⸻

📦 Dependencies
• PHP 7.0+
• No external dependencies (uses built-in PHP functions)
• A small helper file at receiveEmail/lib.php (ensure it’s present)

⸻

📄 License

MIT — feel free to modify and use!

⸻

🙋‍♂️ Author

Developed by Frederico Falcao Questions or ideas? Open an issue or send an email.