Sending Members Emails

Office's ScheduledEmails plugin provides a generic mechanism for building, queuing, and sending personalized messages to members (and other customer entities that have email addresses for that matter). Using this plugin does require installing PHPMailer via Composer. There are two major components to the email system: templates and the queue.

Templates

Templates are stored in ScheduledEmailTemplates. They consist of a subject as well as text and/or HTML content. Placeholder values may be used in template bodies (but not subjects) to fill in customer-specific values. Placeholders use a double curly brace syntax - e.g., {{name}}. Templates may use an unlimited number of placeholders with whatever names are preferred. Queuing code is responsible for providing the corresponding values. Templates can probably be managed by end-users in simpler cases; very complex HTML messages may require more developer-oriented users.

The Queue

The queue is stored in ScheduledEmailQueue. Each entry in the queue represents a single message to a single recipient. The entry's sendDate is approximately when the message will be sent. Each time the plugin's scheduled task runs, it sends all emails that a) are not marked as already sent and b) have a sendDate in the past. If the task runs every five minutes sendDate will be fairly precise. If the task runs once a day sendDate will be more approximate. Messages are queued using the member's ID (as cardNo) rather than email address. This is to avoid updating the queue if the member's email address is edited between when a message is queued and when a message is sent.

The queue's templateData field is responsible for the placeholder values in the template. This field should contain a JSON string with values for its template. For example, if the text body of the template looks like this:

Dear {{name}}

An equity payment of ${{equity}} is due by {{due date}}. Thanks!

The queue templateData would look like this (optional whitespace added for clarity):

{
    "name": "Joey Joe Joe",
    "equity": "20.00",
    "due date": "January 1, 2020"
}

The current expectation is developers can write tasks and/or UIs to populate the queue without having to re-invent the sending & templating components.