nclazz-mail-relay/README.md

Mail Relay - Service
========================

Service for relaying mails from other services or static sites.

Functionality
-----------------------

Mails can be relayed either by invoking the REST-API or by submitting a
form to `/send` with required parameters.

For this to work a `RelayUser` (identified by a token) must first be created to authorize
the request. The `RelayUser` contains all required information to forward an incoming message
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            |