<a id="module-helo"></a>

<a id="helo"></a>

# HELO

This script is executed on `HELO` and `EHLO`. It allows verification of identification.

<a id="variables"></a>

## Variables

These are the pre-defined variables available.

| Variable                                                    | Type   | Read-only   | Description                                  |
|-------------------------------------------------------------|--------|-------------|----------------------------------------------|
| [$arguments](#v-a2)   | array  | yes         | Context/hook arguments                       |
| [$connection](#v-c2)  | array  | yes         | Connection/session bound                     |
| [$transaction](#v-t2) | array  | yes         | Transaction bound                            |
| $context                                                    | any    | no          | Connection bound user-defined (default none) |

<a id="v-a2"></a>

<a id="arguments"></a>

### Arguments

| Array item   | Type   | Example                     | Description                                                  |
|--------------|--------|-----------------------------|--------------------------------------------------------------|
| verb         | string | `"EHLO"`                    | HELO or EHLO command                                         |
| host         | string | `"mail.example.com"`        | HELO hostname of sender                                      |
| extensions   | array  | `["PIPELINING", "SIZE 1...` | The extensions to be sent to the client (if EHLO was issued) |

<a id="v-c2"></a>

<a id="connection"></a>

### Connection

| Array item                                          | Type   | Example                     | Description                                              |
|-----------------------------------------------------|--------|-----------------------------|----------------------------------------------------------|
| id                                                  | string | `"18c190a3-93f-47d7-bd..."` | ID of the connection                                     |
| priority                                            | number | `1`                         | The connection priority                                  |
| remoteip                                            | string | `"192.168.1.11"`            | IP address of the connected client                       |
| remoteport                                          | number | `41666`                     | TCP port of connected client                             |
| remoteptr                                           | string | `"mail.example.org"`        | Reverse DNS (FCrDNS) for remoteip (not always available) |
| remoteuid                                           | number | `106`                       | UNIX socket remote user id (not always available)        |
| localip                                             | string | `"10.0.0.1"`                | IP address of the server                                 |
| localport                                           | number | `25`                        | TCP port of the server                                   |
| serverid                                            | string | `"inbound"`                 | ID of the server                                         |
| [tls](#tls2)  | array  |                             | TLS information (if TLS was started)                     |
| [auth](#au2) | array  |                             | AUTH information (not always available)                  |

<a id="tls2"></a>

<a id="tls"></a>

#### TLS

| Array item                                              | Type   | Example                     | Description                                      |
|---------------------------------------------------------|--------|-----------------------------|--------------------------------------------------|
| protocol                                                | string | `"TLSv1.3"`                 | The protocol                                     |
| cipher                                                  | string | `"ECDHE-RSA-AES256-SHA384"` | The cipher                                       |
| keysize                                                 | number | `256`                       | The keysize                                      |
| sni                                                     | string | `"example.com"`             | The SNI hostname (not always available)          |
| [peercert](#p7) | array  |                             | The peer certificate (if provided by the client) |

<a id="p7"></a>

<a id="peercert"></a>

##### Peercert

| Array item   | Type         | Example   | Description                                                                                          |
|--------------|--------------|-----------|------------------------------------------------------------------------------------------------------|
| x509         | X509Resource |           | An X509Resource to be used with the [`X509`](functions.html.md#X509) class |
| chain        | array        |           | An array of X509Resource (the chain)                                                                 |
| error        | number       | `18`      | The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3))                        |

<a id="au2"></a>

<a id="auth"></a>

#### AUTH

| Array item   | Type   | Example      | Description                          |
|--------------|--------|--------------|--------------------------------------|
| mechanism    | string | `"PLAIN"`    | SASL mechanism (always in uppercase) |
| username     | string | `"mailuser"` | SASL username (not always available) |

<a id="v-t2"></a>

<a id="transaction"></a>

### Transaction

| Array item   | Type   | Example                     | Description           |
|--------------|--------|-----------------------------|-----------------------|
| id           | string | `"18c190a3-93f-47d7-bd..."` | ID of the transaction |

<a id="functions"></a>

## Functions

<a id="Accept"></a>

<a id="helo.Accept"></a>

### Accept([options])

Accept the *HELO* or *EHLO* command. Optionally change the `host` of the sending client, which is written back to the `$connection` variable.

* **Parameters:**
  **options** (*array*) – an options array
* **Returns:**
  doesn’t return, script is terminated

The following options are available in the options array.

> * **extensions** (array) SMTP service extensions to announce in EHLO responses.
> * **host** (string) Change the client HELO hostname for the current connection.
> * **reason** (string) First line of the response. The default is the servers hostname.
> * **reply_codes** (array) The associative array may contain the properties *code* (number) and *enhanced* (array of three numbers). To remove the *enhanced* code set it to `[0,0,0]`. The default *code* is `250` and *enhanced* is not used.
> * **priority** (number) Change the connection priority (0 normal, 1 high).

<a id="Reject"></a>

<a id="helo.Reject"></a>

### Reject([reason[, options]])

Reject the *HELO* or *EHLO* command with a permanent (554) error.

* **Parameters:**
  * **reason** (*string* *or* *array*) – reject message with reason
  * **options** (*array*) – an options array
* **Returns:**
  doesn’t return, script is terminated

The following options are available in the options array.

> * **disconnect** (boolean) Disconnect the client. The default is `false`.
> * **reply_codes** (array) The associative array may contain the properties *code* (number) and *enhanced* (array of three numbers). To remove the *enhanced* code set it to `[0,0,0]`. The default *code* is `554` and *enhanced* is not used.
> * **priority** (number) Change the connection priority (0 normal, 1 high).

<a id="Defer"></a>

<a id="helo.Defer"></a>

### Defer([reason[, options]])

Defer the *HELO* or *EHLO* command with a temporary (450) error.

* **Parameters:**
  * **reason** (*string* *or* *array*) – defer message with reason
  * **options** (*array*) – an options array
* **Returns:**
  doesn’t return, script is terminated

The following options are available in the options array.

> * **disconnect** (boolean) Disconnect the client. The default is `false`.
> * **reply_codes** (array) The associative array may contain the properties *code* (number) and *enhanced* (array of three numbers). To remove the *enhanced* code set it to `[0,0,0]`. The default *code* is `450` and *enhanced* is not used.
> * **priority** (number) Change the connection priority (0 normal, 1 high).

<a id="on-script-error"></a>

## On script error

On script error [`Defer()`](#helo.Defer) is called.

<a id="on-implicit-termination"></a>

## On implicit termination

If not explicitly terminated then [`Accept()`](#helo.Accept) is called.
