From f350e267407d4e4f30ed7912ef59f3d418da18cf Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Sat, 11 Apr 2020 12:33:51 +0200 Subject: [PATCH] #655 add documentation for using SendGrid and for Mailgun API --- docs/email.md | 149 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 118 insertions(+), 31 deletions(-) diff --git a/docs/email.md b/docs/email.md index 3c4faf01..70279541 100644 --- a/docs/email.md +++ b/docs/email.md @@ -31,39 +31,126 @@ SMTP_TIMEOUT This is an example of a configuration using [Mailgun](https://www.mailgun.com/) email service: +```yaml +- SMTP_HOST=smtp.eu.mailgun.org +- SMTP_PORT=465 +- SMTP_TLS=true +- SMTP_USERNAME=postmaster@mg.example.com +- SMTP_PASSWORD=secretpassword +- AUTH_EMAIL_FROM=notify@example.com +- NOTIFY_EMAIL_FROM=notify@example.com ``` - - SMTP_HOST=smtp.eu.mailgun.org - - SMTP_PORT=465 - - SMTP_TLS=true - - SMTP_USERNAME=postmaster@mg.example.com - - SMTP_PASSWORD=secretpassword - - AUTH_EMAIL_FROM=notify@example.com + +#### API + +When you don't want to expose your IP (which is impossible with any SMTP provider) +and for situations when connecting to external SMTP server is impossible due to firewall +settings is setting up an SMTP-to-API bridge and sending messages trough it. + +To use any of containers below with in remark42 environment set following two `SMTP` variables: + +```yaml +- SMTP_HOST=mail +- SMTP_PORT=25 +``` + +#### stevenolen/mailgun-smtp-server + +Here is `docker-compose.yml` configuration part spinning up a container for +[stevenolen/mailgun-smtp-server](https://hub.docker.com/r/stevenolen/mailgun-smtp-server): +```yaml + mailgun: + image: stevenolen/mailgun-smtp-server + container_name: "mail" + hostname: "mail" + + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" + + environment: + - MG_KEY=key-123456789 + - MG_DOMAIN=example.com +``` + +Please note that before +[stevenolen/mailgun-smtp-server#5](https://github.com/stevenolen/mailgun-smtp-server/issues/5) +is fixed, Europe domain names are not supported by this tool. + +### SendGrid + +This is an example of a configuration using [SendGrid](https://sendgrid.com/) email service: + +```yaml +- SMTP_HOST=smtp.sendgrid.net +- SMTP_PORT=465 +- SMTP_TLS=true +- SMTP_USERNAME=apikey +- SMTP_PASSWORD=key-123456789 +- AUTH_EMAIL_FROM=notify@example.com +- NOTIFY_EMAIL_FROM=notify@example.com +``` + +#### API + +When you don't want to expose your IP (which is impossible with any SMTP provider) +and for situations when connecting to external SMTP server is impossible due to firewall +settings is setting up an SMTP-to-API bridge and sending messages trough it. + +To use any of containers below with in remark42 environment set following two `SMTP` variables: + +```yaml +- SMTP_HOST=mail +- SMTP_PORT=25 +``` + +#### fgribreau/smtp-to-sendgrid-gateway + +Here is `docker-compose.yml` configuration part spinning up a container for +[fgribreau/smtp-to-sendgrid-gateway](https://hub.docker.com/r/fgribreau/smtp-to-sendgrid-gateway): +```yaml + sendgrid: + image: fgribreau/smtp-to-sendgrid-gateway + container_name: "mail" + hostname: "mail" + + logging: + driver: json-file + options: + max-size: "10m" + max-file: "5" + + environment: + - SENDGRID_API=key-123456789 ``` ### Gmail Configuration example for Gmail: -``` - - SMTP_HOST=smtp.gmail.com - - SMTP_PORT=465 - - SMTP_TLS=true - - SMTP_USERNAME=example.user@gmail.com - - SMTP_PASSWORD=secretpassword - - AUTH_EMAIL_FROM=example.user@gmail.com +```yaml +- SMTP_HOST=smtp.gmail.com +- SMTP_PORT=465 +- SMTP_TLS=true +- SMTP_USERNAME=example.user@gmail.com +- SMTP_PASSWORD=secretpassword +- AUTH_EMAIL_FROM=example.user@gmail.com +- NOTIFY_EMAIL_FROM=example.user@gmail.com ``` ### Amazon SES Configuration example for [Amazon SES](https://aws.amazon.com/ses/) (us-east-1 region): -``` - - SMTP_HOST=email-smtp.us-east-1.amazonaws.com - - SMTP_PORT=465 - - SMTP_TLS=true - - SMTP_USERNAME=access_key_id - - SMTP_PASSWORD=secret_access_key - - AUTH_EMAIL_FROM=notify@example.com - +```yaml +- SMTP_HOST=email-smtp.us-east-1.amazonaws.com +- SMTP_PORT=465 +- SMTP_TLS=true +- SMTP_USERNAME=access_key_id +- SMTP_PASSWORD=secret_access_key +- AUTH_EMAIL_FROM=notify@example.com +- NOTIFY_EMAIL_FROM=notify@example.com ``` A domain or an email that will be used in `AUTH_EMAIL_FROM` or `NOTIFY_EMAIL_FROM` must first be [verified](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domain-procedure.html). @@ -82,11 +169,11 @@ AUTH_EMAIL_CONTENT_TYPE AUTH_EMAIL_TEMPLATE ``` -After `SMTP_` variables are set, you can allow email authentication by setting these two variables: +After you set `SMTP_` variables, you can allow email authentication by setting these two variables: -``` - - AUTH_EMAIL_ENABLE=true - - AUTH_EMAIL_FROM=notify@example.com +```yaml +- AUTH_EMAIL_ENABLE=true +- AUTH_EMAIL_FROM=notify@example.com ``` @@ -97,7 +184,7 @@ Usually, you don't need to change/set anything else. In case if you want to use Here is the list of variables which affect email notifications: -``` +```yaml NOTIFY_TYPE NOTIFY_EMAIL_FROM NOTIFY_EMAIL_VERIFICATION_SUBJ @@ -106,10 +193,10 @@ ADMIN_SHARED_EMAIL NOTIFY_EMAIL_ADMIN ``` -After `SMTP_` variables are set, you can allow email notifications by setting these two variables: +After you set `SMTP_` variables, you can allow email notifications by setting these two variables: -``` - - NOTIFY_TYPE=email - # - NOTIFY_TYPE=email,telegram # this is in case you want to have both email and telegram notifications enabled - - NOTIFY_EMAIL_FROM=notify@example.com +```yaml +- NOTIFY_TYPE=email +# - NOTIFY_TYPE=email,telegram # this is in case you want to have both email and telegram notifications enabled +- NOTIFY_EMAIL_FROM=notify@example.com ```