Emails - samuelgrant/fight-for-kidz GitHub Wiki

Application Emails

Note: The mail feature of this page is in constant development. As such this page maybe limited, contact @samuelgrant if you have questions or believe this page is missing something.

This application has several core functions that make use of emails. Emails can be sent via an SMTP or API driver. For information on setting up a development testing mail environment Click Here.

Current functions that use emails:

  • Create new admin account
  • Disable/enable admin account
  • Password reset request
  • Password reset notification
  • Sending emails to groups
  • Submitting contact forms (one email to sender, one to admin)

The email system can be difficult to produce as global spam filters may flag emails as spam if certain conditions aren't met. For more information view: https://serverfault.com/a/48439.

To reduce the spam index on bulk emails, text only versions of the email are sent along with the html version. The html content is converted to text using the Html2Text library. See the third party code wiki page for a link to this library on Github.

Testing Email Environment

Mailtrap.io is a free service that allows you to send test emails via a variety of ways including API and SMTP drivers. This is the best way to test your emails as it allows you to send emails to real (or fake) email addresses that will never be sent. Instead the emails go to a dashboard on your account, so you can see what they would look like.

Mailtrap also allows you to view the message in a variety of formats including HTML, raw text and provides a spam check function.

Setting up Your Environment

  • Register an account here - You can use your GitHub account.
  • Create an inbox here.
  • Find your SMTP settings. They should be on the main section of your screen.
  • Setup the mail section your .env file so it looks like this:
MAIL_DRIVER=smtp
MAIL_HOST="smtp.mailtrap.io"
MAIL_PORT=2525
MAIL_USERNAME=<<YOUR USERNAME HERE>>
MAIL_PASSWORD=<<YOUR PASSWORD HERE>>
MAIL_ENCRYPTION=tls

Use quotes around the username and password.

Setting up global from address and name

The global from address and name are configured in the .env file. A suggested configuration is shown below..

MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="Fight for Kidz"

Setting up admin email

The ADMIN_EMAIL in the .env file is set to the email address that should receive notifications from the system. These notifications are currently limited to whenever a contact form enquiry has been received. A suggested configuration is shown below..

ADMIN_EMAIL="[email protected]"

In the future, additional notifications could be added, such as weekly/monthly summaries of applications received, website visitor counts, etc.

Setting up for background sending

To prevent the application timing out and/or blocking the UI, it is very important to have mail sending in the background.

To do this, please set your .env file as follows:

QUEUE_DRIVER=database

This will set the queue system to record queued jobs in the database. Ensure that your database has the 'jobs' and 'failed-jobs' tables, and if not, migrate your database to add them.

In order to execute the jobs in the queue, run the php artisan queue:work command. The worker daemon will execute all jobs in the queue, and then listen for any new ones.

On the production (shared) server, a cron job has been set to run the Laravel scheduler. /path/to/php -d register_argc_argv=1 /path/to/artisan schedule:run >> /dev/null 2>&1

It is important to include the register_argc_argv=1 as the command will fail if this is not included.

Laravel scheduler has been configured to run the php artisan queue:work --tries=3 --sansdaemon command every minute. This configuration can be observed in the app/Console/Kernel.php file: $schedule->command('queue:work --sansdaemon --tries=3')->everyMinute();

The --sansdaemon option is provided by orbogenius/sansdaemon, and means that the worker will exit after executing all jobs, rather than listening for new ones. This prevents worker processes from accumulating and reaching the process limit set by the hosting platform.

By including --tries=3 in the command, any jobs that are continually failing will be put into the failed jobs table. There are currently no provision made for reattempting to send these emails.

Setting up rich text editing

In order to use the CKeditor script, the .js files need to be published to the public folder. As there is a large number of files, they have not been tracked on git. This means you will need to run the following command to publish them:

php artisan vendor:publish --tag=ckeditor

Currently, all rich text inputs are being sanitized by Purifier, meaning that malicious scripts entered in the editor should be prevented from executing. The risk from such attacks is low at any rate, as only trusted persons should be granted access to the admin dashboard.

Attachments

The user is able to attach multiple files to emails to groups. The file types are limited to the following: doc,docx,bmp,gif,jpg,jpeg,png,pdf,rtf,xls,xlsx,txt

This list can be configured in the mail controller's 'sendMail()' method, for back end validation. Front end validation is to be completed.

In order to log email jobs in the database, any attached files have to be stored on disk temporarily (otherwise we would have to serialize the files and store in the database, which throws an exception). These files are stored in /storage/app/private/temp/.

To prevent buildup of these files, a QueueServiceProvider has been created. After each queue worker completes a job, the code in this provider checks whether there are any jobs remaining. When there are no jobs remaining, all files in the temp directory are deleted.

Creating an Email

See Laravel official documentation for create and sending mail.

Limitations

  • Validation on mail form need to be completed for front end so that the user doesn't lose their work on a failed back-end validation.
  • User cannot select individual contacts to send emails to. They will need to add these individuals to a custom group and then email the custom group.
  • No record of sent emails (we could perhaps set it to send a copy of each email to the logged in user, or to a fixed email address)
  • Attachments must all be selected at the same time, cannot add / remove individual attachments
  • File upload limit currently 2MB, will need to increase for production.

Unit/Feature Tests: tests/Feature/MailTest.php