diff --git a/README.md b/README.md
new file mode 100644
index 0000000..785c472
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+## EPICS2SMS
+
+Monitor one or more EPICS PVs and send an SMS alert via PSI mail infrastructure.
+
+This tool **does not use local `/usr/sbin/sendmail`**.  It sends mail via **direct SMTP**
+to `smtp.psi.ch` to ensure the message is handled as a registered
+system/application sender.
+
+### Files
+
+- `epics2sms.sh`  
+  EPICS polling + alert logic (send once per outage; reset when OK again).
+
+- `smtp_send.py`  
+  SMTP transport helper (no authentication).  Sets both header `From:` and
+  envelope sender (`MAIL FROM`) to the configured sender address.
+
+### Why SMTP instead of sendmail?
+
+On beamline console hosts, local `sendmail` may be routed through internal relays
+or firewall rules and can lead to **silent drops** for mail-to-SMS gateways.
+Direct SMTP to `smtp.psi.ch` makes the transport path explicit and reproducible.
+
+### Requirements
+
+- EPICS CA tools available on the host (`caget`).
+- Python 3 available (`python3`).
+- Network access from the host to `smtp.psi.ch:25`.
+
+### Configuration
+
+Edit `epics2sms.sh`:
+
+- `PV_NAME` and threshold logic (example currently uses `value > 0` as OK).
+- `RECIPIENTS`  
+  Include the Swisscom gateway address:
+  - `079XXXXXXX@mail2sms.swisscom.com`
+- `FROM_ADDR`  
+  Must be a **registered PSI system/application sender**, e.g. `cSAXS@psi.ch`.
+
+`FROM_ADDR` is critical: messages from host/user addresses like
+`e23080@x12sa-cons-02.psi.ch` may be filtered and never reach the SMS gateway.
+
+### Quick test
+
+Send a normal email:
+
+```
+python3 smtp_send.py --to andreas.menzel@psi.ch --from-addr cSAXS@psi.ch "Test $(date)"
+```
+
+Send an SMS (via mail2sms):
+
+```
+python3 smtp_send.py --to 079XXXXXXX@mail2sms.swisscom.com --from-addr cSAXS@psi.ch "SMS test $(date)"
+```
+
+### Run the monitor
+
+```
+./epics2sms.sh
+```
+
+Behavior:
+
+- polls the PV at `POLL_INTERVAL` while OK
+- if NOT OK, sends **one** alert
+- repeats checks at `ERROR_INTERVAL` while NOT OK
+- once OK again, the alert state resets
+
+### Notes / Troubleshooting
+
+- If no SMS arrives but SMTP returns success, ask IT to check Exchange/relay
+  transport rules for the registered sender and the mail2sms gateway domain.
+- Use `smtp_send.py` directly for transport debugging (it should return non-zero
+  on errors).