@itentialopensource/adapter-email/docs/DOCUMENTATION.md

Email notification adapter

Email Adapter
===

This adapter is used to send out email notifications from Pronghorn. The current version 
of adapter-email uses the "nodemailer" client library to deliver email notifications. 
Additional information may be found at the [NodeMailer Website](https://nodemailer.com/about/)  

Table of Contents
---

- [Configuration](#markdown-header-Configuration)

# Configuration
---

**Pre-Requisites:**

To enable this adapter, you will need to edit Pronghorn's properties to include
this adapter. To do this, you can either edit your properties from the
"Settings -> Properties" page or you can edit the _properties.json_ file directly.

To include the adapter, you need something like the following examples in both your
`adapterProps` section and your `brokerProps` section.  

## Adapter Properties
---

This first example shows how to connect to a "sendmail" agent running on localhost port 25 without authentication:  

```
{
    "id": "email",
    "type": "Email",
    "properties": {
        "host": "localhost",
        "port": 25,
        "secure": false
    }
}
```

You can add authentication and encryption if your mail exchange relay supports it:  

```
{
	"id": "email",
	"type": "Email",
	"properties": {
	    "host": "localhost",
	    "port": 587,
	    "secure": true,
	    "auth": {
	        "user": "exampleUser",
	        "pass": "examplePass"
	    }
	}
}
```

Nodemailer also provides for many pre-defined _services_ to be configured with minimal configuration.  For a list these services, refer to the [Nodemailer Well-Known Services](https://nodemailer.com/smtp/well-known/).  

```
{
    "id": "email",
    "type": "Email",
    "properties": {
        "service": "example server name (from list https://nodemailer.com/smtp/well-known/ )",
    }
}
```

```
{
    "id": "email",
    "type": "Email",
    "properties": {
        "service": "example server name (from list https://nodemailer.com/smtp/well-known/ )",
        "auth": {
            "user": "exampleUser",
            "pass": "examplePass"
        }
    }
}
```

The full json schema describing the properties supported by the adapter can be found at the following location:  
`/opt/pronghorn/current/node_modules/@itential/adapter-email/propertiesSchema.json`  

## Broker Properties
---

You will also need the following in the `brokerProps` section:

```
"brokerProps": {
    "notification": ["email"]
}
```

Once you are done configuring the email adapter, save your properties file and restart Pronghorn for the changes to take effect.

# Troubleshooting
---

The following log files are useful for troubleshooting issues when delivering mail to a sendmail agent:

* /var/log/messages
* /var/log/maillog