<commit_before>As the name implies, the https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin.

== Prerequisites

Ensure that you have Kill Bill, Kaui, and the database set up as explained in the https://docs.killbill.io/latest/getting_started.html[Getting Started Guide].

== Overview 

The https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a https://docs.killbill.io/latest/notification_plugin.html[notification plugin]. It listens to https://docs.killbill.io/latest/notification_plugin.html#_kill_bill_events_handled_by_notification_plugin[events] and sends emails accordingly.

Currently, the email notification plugin supports the following events:

[options="header",cols="1,1"]
|===
|Event Type   |Email Description
//-------------
|INVOICE_CREATION   |The customer will receive an email informing them that a new invoice is available.  
|INVOICE_NOTIFICATION   |The customer will receive an email about upcoming invoices (the time at which to send the email is configured through the Kill Bill system property `org.killbill.invoice.dryRunNotificationSchedule`).  
|INVOICE_PAYMENT_SUCCESS   |The customer will receive an email after each successful payment or refund.
|INVOICE_PAYMENT_FAILED   |The customer will receive an email after each failed payment.  
|SUBSCRIPTION_CANCEL   | The customer will receive an email at the time a subscription was requested to be canceled and/or at the effective date of the subscription cancellation.  
|===

To send an email the following is required:

* The tenant or account must be configured to permit such event(s). This is explained in the <<Plugin Configuration>> section below.

* The account for which the emails need to be sent must have certain fields set. This is explained in the <<Account Configuration>> section below.



== Plugin Installation

A plugin can be installed via the https://github.com/killbill/killbill-cloud/blob/master/kpm[Kill Bill Package Manager (KPM)]. For this, please follow the steps given below:

. Ensure that you have kpm installed as explained https://github.com/killbill/killbill-cloud/tree/master/kpm#kpm-installation[here].

. Install the plugin using the following kpm command (Replace `<path_to_install_plugin>` with the path where you want to install the plugin. This path should match the path specified by the `org.killbill.osgi.bundle.install.dir` property in the Kill Bill configuration file):
[source,bash]
kpm install_java_plugin email-notifications --destination=<path_to_install_plugin>

. Verify that the plugin is installed properly. This can be done by ensuring that the plugin JAR is present at the `path_to_install_plugin` specified in the previous step. Alternatively, you can also open `kpm` in https://docs.killbill.io/latest/userguide_kaui.html[Kaui] and verify that the email notification plugin is running as follows:
image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/email-notification-plugin/kaui_email_notification_plugin.png[align=center]

. If you would like to make changes to the plugin, you can clone the plugin code, build and deploy it as explained https://github.com/killbill/killbill-email-notifications-plugin[here].


== Database Configuration

The email-notification-plugin requires some additional database tables. To create these tables, please follow the steps given below:

. Connect to the Kill Bill database.

. Run the https://github.com/killbill/killbill-email-notifications-plugin/blob/master/src/main/resources/ddl.sql[email-notification-plugin] DDL.

== Plugin Configuration

In order to use the email notification plugin, a tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.

The tenant/account configuration can be done by executing the required API endpoints via *cURL* as explained below:

[[tenant-config,Tenant Configuration]]
. *Configure the tenant* using the following cURL command (Replace `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS`):
[source,bash]
curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d 'org.killbill.billing.plugin.email-notifications.defaultEvents=<events>
org.killbill.billing.plugin.email-notifications.smtp.host=127.0.0.1
org.killbill.billing.plugin.email-notifications.smtp.port=25
org.killbill.billing.plugin.email-notifications.smtp.useAuthentication=true
org.killbill.billing.plugin.email-notifications.smtp.userName=uuuuuu
org.killbill.billing.plugin.email-notifications.smtp.password=<PASSWORD>
org.killbill.billing.plugin.email-notifications.smtp.useSSL=false
org.killbill.billing.plugin.email-notifications.smtp.sendHTMLEmail=true
org.killbill.billing.plugin.email-notifications.smtp.defaultSender=<EMAIL>' \
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
     
. If you are on Windows, we recommend that you use https://git-scm.com/download/win[Git Bash] to run the above command. Since the above is a multiline cURL command, it may not run properly in the standard windows command prompt. Alternatively, you may also use https://www.postman.com/[Postman] to execute the tenant configuration endpoint as explained https://docs.killbill.io/latest/postman.html[here].

. *Configure the account* using the following cURL command (Replace `{accountId}` with the id of the account for which emails need to be sent and `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `"INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"`):
[source,bash]
curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: application/json' \
     -d '[<events>]' \
    http://127.0.0.1:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
   
. Note that either the *tenant* or the *account* should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:

.. If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.

.. If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.

.. If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.

== Account Configuration

The account for which emails need to be sent, needs to have the `email` and `locale` fields set. In addition, the <<email-templates>> used by the notification plugin also require the  `company`, `address1`, `city`, `state`, `postalCode`, `country` fields also set on the Account.

Thus, ensure that the account is created using the following cURL command (Replace `<email_id>` with the email id where you would like to receive the email and change values for the other fields as required):
[source, bash]
curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "name": "<NAME>", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
"http://127.0.0.1:8080/1.0/kb/accounts"


== SMTP Server Notes

In order to be able to use the email notification plugin to send emails, a local SMTP server is required. 



We typically use the `namshi/smtp` docker image as follows to start a local SMTP server on port 25:

[source, bash]
docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp

Alternatively, if you would like to use a non-docker based SMTP server, you can use https://www.mailslurper.com/[MailSlurper]. MailSlurper is a small handy SMTP server that can be useful for development. It can be downloaded and configured as explained https://www.mailslurper.com/[here].


== Testing the plugin

Once the plugin is installed and configured as explained above, it can be used for sending emails. You can verify that the plugin is working correctly by following the steps given below:

. Start a local SMTP server as explained in the <<SMTP Server Notes>> section above.

. Create a tenant as follows (specify the required `apiKey` and `apiSecret`):
[source,bash]
curl -v \
    -X POST \
    -u admin:password \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
    "http://127.0.0.1:8080/1.0/kb/tenants"

. Configure the tenant as specified in the <<tenant-config>> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.<commit_msg>Email Notification Plugin round 2<commit_after>As the name implies, the https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a plugin that sends out emails when certain events occur. This document covers how to install, test, and use this plugin.

== Prerequisites

Ensure that you have Kill Bill, Kaui, and the database set up as explained in the https://docs.killbill.io/latest/getting_started.html[Getting Started Guide].

== Overview 

The https://github.com/killbill/killbill-email-notifications-plugin[email notification plugin] is a https://docs.killbill.io/latest/notification_plugin.html[notification plugin]. It listens to https://docs.killbill.io/latest/notification_plugin.html#_kill_bill_events_handled_by_notification_plugin[events] and sends emails accordingly.

Currently, the email notification plugin supports the following events:

[options="header",cols="1,1"]
|===
|Event Type   |Email Description
//-------------
|INVOICE_CREATION   |The customer will receive an email informing them that a new invoice is available.  
|INVOICE_NOTIFICATION   |The customer will receive an email about upcoming invoices (the time at which to send the email is configured through the Kill Bill system property `org.killbill.invoice.dryRunNotificationSchedule`).  
|INVOICE_PAYMENT_SUCCESS   |The customer will receive an email after each successful payment or refund.
|INVOICE_PAYMENT_FAILED   |The customer will receive an email after each failed payment.  
|SUBSCRIPTION_CANCEL   | The customer will receive an email at the time a subscription was requested to be canceled and/or at the effective date of the subscription cancellation.  
|===

In addition, it can be extended to to handle other types of events as well. This is explained in the <<Configuring the plugin for additional events>> section below.

To send an email the following is required:

* The tenant or account must be configured to permit such event(s). This is explained in the <<Plugin Configuration>> section below.

* The account for which the emails need to be sent must have certain fields set. This is explained in the <<Account Configuration>> section below.



== Plugin Installation

A plugin can be installed via the https://github.com/killbill/killbill-cloud/blob/master/kpm[Kill Bill Package Manager (KPM)]. For this, please follow the steps given below:

. Ensure that you have kpm installed as explained https://github.com/killbill/killbill-cloud/tree/master/kpm#kpm-installation[here].

. Install the plugin using the following kpm command (Replace `<path_to_install_plugin>` with the path where you want to install the plugin. This path should match the path specified by the `org.killbill.osgi.bundle.install.dir` property in the Kill Bill configuration file):
[source,bash]
kpm install_java_plugin email-notifications --destination=<path_to_install_plugin>

. Verify that the plugin is installed properly. This can be done by ensuring that the plugin JAR is present at the `path_to_install_plugin` specified in the previous step. Alternatively, you can also open `kpm` in https://docs.killbill.io/latest/userguide_kaui.html[Kaui] and verify that the email notification plugin is running as follows:
image:https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/email-notification-plugin/kaui_email_notification_plugin.png[align=center]

. If you would like to make changes to the plugin, you can clone the plugin code, build and deploy it as explained https://github.com/killbill/killbill-email-notifications-plugin[here].


== Database Configuration

The email-notification-plugin requires some additional database tables. To create these tables, please follow the steps given below:

. Connect to the Kill Bill database.

. Run the https://github.com/killbill/killbill-email-notifications-plugin/blob/master/src/main/resources/ddl.sql[email-notification-plugin] DDL.

== Plugin Configuration

In order to use the email notification plugin, a tenant needs to be configured with the SMTP properties required for sending emails. Additionally, the tenant can also be configured with the events for which emails should be sent. In addition to the per-tenant configuration, the plugin also allows a more granular account-level configuration for the set of emails to be sent for the particular account. Thus, either the tenant or the account needs to be configured with the events for which the email needs to be sent.

The tenant/account configuration can be done by executing the required API endpoints via *cURL* as explained below:

[[tenant-config,Tenant Configuration]]
. *Configure the tenant* using the following cURL command (Replace `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the tenant to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `org.killbill.billing.plugin.email-notifications.defaultEvents=INVOICE_CREATION,INVOICE_PAYMENT_SUCCESS`):
[source,bash]
curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: text/plain' \
     -d 'org.killbill.billing.plugin.email-notifications.defaultEvents=<events>
org.killbill.billing.plugin.email-notifications.smtp.host=127.0.0.1
org.killbill.billing.plugin.email-notifications.smtp.port=25
org.killbill.billing.plugin.email-notifications.smtp.useAuthentication=true
org.killbill.billing.plugin.email-notifications.smtp.userName=uuuuuu
org.killbill.billing.plugin.email-notifications.smtp.password=<PASSWORD>
org.killbill.billing.plugin.email-notifications.smtp.useSSL=false
org.killbill.billing.plugin.email-notifications.smtp.sendHTMLEmail=true
org.killbill.billing.plugin.email-notifications.smtp.defaultSender=<EMAIL>' \
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
     
. If you are on Windows, we recommend that you use https://git-scm.com/download/win[Git Bash] to run the above command. Since the above is a multiline cURL command, it may not run properly in the standard windows command prompt. Alternatively, you may also use https://www.postman.com/[Postman] to execute the tenant configuration endpoint as explained https://docs.killbill.io/latest/postman.html[here].

. *Configure the account* using the following cURL command (Replace `{accountId}` with the id of the account for which emails need to be sent and `<events>` with a comma-separated list of the events for which the emails need to be sent. For example, to configure the account to send emails for *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS*, specify `"INVOICE_CREATION", "INVOICE_PAYMENT_SUCCESS"`):
[source,bash]
curl -v \
     -X POST \
     -u admin:password \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'X-Killbill-CreatedBy: admin' \
     -H 'Content-Type: application/json' \
     -d '[<events>]' \
    http://1172.16.17.32:8080/plugins/killbill-email-notifications/v1/accounts/{accountId}
   
. Note that either the *tenant* or the *account* should be configured with the events for which emails need to be sent, otherwise, emails will not be sent. Some scenarios for this:

.. If a tenant is configured with some events, but the account is not configured, then emails will be sent based on what is configured at the tenant level.

.. If a tenant is not configured with any events but the account is configured with events, then emails will be sent based on what is configured at the account level.

.. If both tenant and account are configured with separate events, emails will be sent based on the events configured for both.

== Account Configuration

The account for which emails need to be sent, needs to have the `email` and `locale` fields set. In addition, the <<email-templates>> used by the notification plugin also require the  `company`, `address1`, `city`, `state`, `postalCode`, `country` fields also set on the Account.

Thus, ensure that the account is created using the following cURL command (Replace `<email_id>` with the email id where you would like to receive the email and change values for the other fields as required):
[source, bash]
curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "name": "<NAME>", "email": "<email_id>", "currency": "USD", "company": "Acme Corporation", "locale":"en_US", "address1": "57 Academy Drive","city": "Oak Creek","state": "WI","postalCode": "53154", "country": "US"}' \
"http://127.0.0.1:8080/1.0/kb/accounts"


== SMTP Server Notes

In order to be able to use the email notification plugin to send emails, a local SMTP server is required. 



We typically use the `namshi/smtp` docker image as follows to start a local SMTP server on port 25:

[source, bash]
docker run -tid --name smtp_server -p 25:25  -e DISABLE_IPV6=true namshi/smtp

Alternatively, if you would like to use a non-docker based SMTP server, you can use https://www.mailslurper.com/[MailSlurper]. MailSlurper is a small handy SMTP server that can be useful for development and testing. It can be downloaded and configured as explained https://www.mailslurper.com/[here].


== Testing the plugin

Once the plugin is installed and configured as explained above, it can be used for sending emails. You can verify that the plugin is working correctly by following the steps given below:

. Start a local SMTP server as explained in the <<SMTP Server Notes>> section above.

. Create a tenant as follows (specify the required `apiKey` and `apiSecret`):
[source,bash]
curl -v \
    -X POST \
    -u admin:password \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
    "http://127.0.0.1:8080/1.0/kb/tenants"

. Configure the tenant as specified in the <<tenant-config>> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.
{'fraction_non_alphanumeric': 0.09343829454332095, 'fraction_numerical': 0.007480930960297281, 'mean_word_length': 4.326302083333333, 'pattern_counts': {'":': 24, '<': 47, '<?xml version=': 0, '>': 47, 'https://': 32, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7053457', 'n_tokens_mistral': 6099, 'n_tokens_neox': 5758, 'n_words': 2309}