Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

AWS SES -- email notification #550

Merged
merged 6 commits into from
Jun 23, 2024
Merged

AWS SES -- email notification #550

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ffc939b
* Updated email notification plugin, adding info about using AWS SES.
vnandwana Apr 23, 2024
cf65c5f
* XRay daemon now comes preinstalled with AMI. Removed the installati…
vnandwana Apr 25, 2024
d83cc75
Addressed review comments.
vnandwana May 26, 2024
dc3dfe0
Merge branch 'v3' into ses-email-notification
sbrossie May 30, 2024
3e5f3a3
Addressed review comments.
vnandwana Jun 3, 2024
b78a292
Addressed review comments.
vnandwana Jun 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 62 additions & 36 deletions userguide/tutorials/email-notification-plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
= Email Notification Plugin

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.
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, with support for both SMTP and AWS SES for sending email notifications.

== 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__].

* Ensure that you have https://curl.haxx.se/[_cURL_] installed. If you are on Windows, we recommend that you use https://git-scm.com/download/win[_Git Bash_] to run the `cURL` commands.

* If you plan to use AWS SES, obtain your AWS SES credentials (access key and secret key) and ensure that the IAM user has the `ses:SendEmail` permission.

== 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/kill_bill_events.html[Kill Bill Events] and sends emails accordingly.
Expand Down Expand Up @@ -61,12 +63,36 @@ The email-notification-plugin requires some additional database tables. To creat
[[plugin_configuration]]
== 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.
In order to use the email notification plugin, you need to configure either SMTP or AWS SES settings. Below are the steps to configure both:

=== AWS SES Configuration
To enable AWS SES for email notifications, add the following properties into `killbill.properties`. The default sender's email must be verified in AWS SES.

[source,bash]
org.killbill.email.notification.via.ses=true
org.killbill.mail.from=<Default sender's email>
org.killbill.aws.region=<AWS region, default region is us-east-1>

AWS SES requires authentication for sending emails. System-wide environment variables can be configured for all users by appending them to the `/etc/environment` file. Open the `/etc/environment` file in a text editor with root privileges, set the following variables:

[source,bash]
AWS_ACCESS_KEY_ID=<AWS access key ID>
AWS_SECRET_ACCESS_KEY=<AWS access secret>


The tenant/account configuration can be done by executing the required API endpoints via *cURL* as explained below:
Reboot the system to apply the changes.


[NOTE]
*Note:* Ensure that the credentials used have the necessary permissions, specifically `ses:SendEmail`, on the resource arn:aws:ses:<region>:<account>:identity/<sender's email>.

=== SMTP Configuration
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Move the text 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. to the Configure Events section below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't move this as the statement is good for SMTP configuration.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but from what I read, the account configuration is now moved to the Configure Events section, hence I suggested moving the above text to the Configure Events. If you disagree, feel free to leave it as it is and merge the PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets keep this in SMTP as the following is not applicable for SES:
"per-tenant configuration" or "either the tenant or the account needs to be configured".

I'm not authorized to merge code to any of the public repositories.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@reshmabidikar If no further changes are required, kindly merge this branch. I don't have permission to merge code to this branch. Thank you.


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

[[tenant-config]]
. *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`):
*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`):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this on purpose (no more space) ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is how it was earlier. I just removed the dot (.) from the beginning of the line so that it doesn't add a number section.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think tenant/account configuration (Steps 1 and 2 in the plugin configuration section) would be required when AWS SES is used as well.

If you agree, we can maybe add a section below SMTP Server Notes called AWS SES Specific Configuration that only includes the additional configuration for AWS SES and make it clear that this is only the additional configuration.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tenant configuration mentioned in the SMTP section is not required for AWS SES. I have made some changes to the doc, hopefully, these comments are addressed. Kindly check when you get a chance. Thank you.

[source,bash]
curl -v \
-X POST \
Expand All @@ -85,29 +111,24 @@ 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=xxx@yyy.com' \
http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/killbill-email-notifications
+

[NOTE]
*Note:* On Windows systems, multiline `cURL` commands like the one above do not run property when `cURL` is used on the standard windows command prompt. So, we recommend using either https://git-scm.com/download/win[_Git Bash_] or https://www.postman.com/[_Postman_] 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.
[[smtp_server_notes]]
=== SMTP Server Notes

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

.. 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.

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 in its https://github.com/mailslurper/mailslurper/wiki/Getting-Started[_documentation_].


[[account_configuration]]
== Account Configuration
Expand All @@ -129,27 +150,32 @@ curl -v \
-d '{ "name": "John Doe", "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"

=== Configure Events
*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}

[[smtp_server_notes]]
== 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:
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:

[source, bash]
docker run -tid --name smtp_server -p 25:25 -e DISABLE_IPV6=true namshi/smtp
.. 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.

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 in its https://github.com/mailslurper/mailslurper/wiki/Getting-Started[_documentation_].
.. 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.

== 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, "SMTP Server Notes">> section.
. If you're using SMTP, start a local SMTP server as explained in the <<smtp_server_notes, "SMTP Server Notes">> section. Otherwise, if you're using AWS SES, make sure it's configured as explained in the <<plugin_configuration, "Plugin Configuration">> section.

. Ensure that Kill Bill is running either in https://docs.killbill.io/latest/development.html#_running_the_application[_standalone_] mode or in https://docs.killbill.io/latest/getting_started.html[_Tomcat_].

Expand All @@ -166,8 +192,6 @@ curl -v \
-d '{ "apiKey": "bob", "apiSecret": "lazar"}' \
"http://127.0.0.1:8080/1.0/kb/tenants"

. Configure the tenant as specified in the <<tenant-config, "Plugin Configuration">> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.

. Create an account as follows (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 \
Expand All @@ -185,6 +209,8 @@ curl -v \

. If successful, the command above returns a `Location` header like \http://127.0.0.1:8080/1.0/kb/accounts/eda3e357-20a1-456d-a9b3-b39ca3db8020. Copy the `account_id` in the header (`eda3e357-20a1-456d-a9b3-b39ca3db8020` in this case) and save it for future use.

. If you're using SMTP, configure the tenant as specified in the <<tenant-config, "Plugin Configuration">> section above with *INVOICE_CREATION* and *INVOICE_PAYMENT_SUCCESS* events.

. Add a payment method as follows (replace `<account_id>` with the account id obtained above):
[source, bash]
curl -v \
Expand Down
12 changes: 0 additions & 12 deletions userguide/tutorials/metrics-cloudwatch.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,6 @@ After editing the file, go to your AWS EC2 dashboard and *reboot the
instance* so the new configuration file will be read. If you have more
than one instance, follow the same procedure for each one.

== Install the X-Ray daemon

AWS X-Ray is a service that collects and analyzes data from your applications. A daemon is a process that runs in the background to do a job whenever it is needed. The X-Ray daemon uploads application metrics to X-Ray in batches to be processed. X-Ray then forwards this data to CloudWatch for display.

To setup the daemon, log in to your EC2 instance and run the following commands:

```
curl https://s3.dualstack.us-east-1.amazonaws.com/aws-xray-assets.us-east-1/xray-daemon/aws-xray-daemon-3.x.deb -o /home/ubuntu/xray.deb
sudo dpkg -i /home/ubuntu/xray.deb
```

If you have more than one instance, repeat these commands on each one.

== Create an IAM Policy

Expand Down
Loading