Add README.md

README.md

@@ -0,0 +1,107 @@
+# 📬 Email Webhook Receiver for ForwardEmail.net
+
+This is a simple PHP webhook endpoint designed to receive incoming emails from [ForwardEmail.net](https://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:
+   ```bash
+   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.
+
+⸻
+
+🛠️ Optional Per-Sender Automation
+
+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.