From 1c83636c8e85d93bb10b6ddd43bfd1494ffbdd88 Mon Sep 17 00:00:00 2001
From: Niclas Thobaben <niclas.thobaben@nclazz.de>
Date: Tue, 15 Feb 2022 13:37:47 +0100
Subject: [PATCH] updated README.md

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/README.md b/README.md
index 2c58d23..c653364 100644
--- a/README.md
+++ b/README.md
@@ -14,3 +14,51 @@ the request. The `RelayUser` contains all required information to forward an inc
 to the expected target mail address.
 
 
+Form Usage
+-----------------------
+
+The following HTML snippet shows the basic usage:
+
+```html
+
+<form action="https://api.nclazz.de/send" method="post">
+    <input type="hidden" name="token" value="3c1a04d16008a84c">
+    <input type="text" name="subject" placeholder="Subject">
+    <input type="email" name="from" placeholder="From">
+    <textarea name="content"></textarea>
+    
+    <input type="submit" value="submit">    
+</form>
+
+```
+
+The following fields are available and be inserted into the form.
+
+|Name               |Type       |Description                                            |Restriction                                                |
+|-------------------|-----------|-------------------------------------------------------|-----------------------------------------------------------|
+|`token`            |`text`     |The token of the Relays Account to use                 |**Mandatory**. Account must first be created               |
+|`subject`          |`text`     |The subject of the message to be send                  |**Mandatory**. Can be any string but must *not* be empty   |
+|`from`             |`email`    |The email of the form submitter                        |**Mandatory**. Must be a valid address by [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322)|
+|`content`          |`text`     |The content of the message.                            |**Mandatory**. Must *not* be empty                         |
+|`onSuccess`        |`url`      |Redirects to this URL on success                       |Must be a valid URL                                        |
+|`onError`          |`url`      |Redirects to this URL on failure. Passes errors as query.|Must be a valid URL.                                     |
+
+
+Form Error Handling
+-----------------------
+
+The form will always return a success, no matter if the account exists or not. This is done to mitigate
+reconnaissance activities. Errors on the submitted form on the other hand will be handled by a redirect 
+either to the referer set in `Referer` header or by providing `onError` url.
+
+If an error occurs the affected properties will be set as query parameters with the type of validation
+violation.
+
+The affected properties can be `subject`, `from` or `content`.
+
+The following error codes are available:
+
+|Code           |Description                                            |   
+|---------------|-------------------------------------------------------|
+|`NotBlank`     |Property is mandatory and must be set                  |
+|`Pattern`      |Property is provided with an illegal format            |
\ No newline at end of file