The Xataface Email module allows you to convert your database into a mailing list so that you can easily send email to any found set of records, as long as the records contain an email address to send to.
Send email to any found set.
Mail merge macros
HTML Email support (uses NicEdit WYSIWYG editor for email editing).
Opt out support (allows recipients to opt out of your mailing list).
Download and extract Email directory so that it is located inside the xataface/modules directory (i.e. xataface/modules/Email)
Add the following to the [_modules] section of your application's conf.ini file:
Configure the [email] action in your application's actions.ini file. See the section called 'Configuration' for configuration details.
Add a line to your crontab file to send out pending email periodically. The line should look like:
* * * * * /usr/bin/php <cronpath> <indexpath> <indexurl> mail
where <cronpath> is the absolute path to the cron.php script.
<indexpath> is the absolute path to your application's index.php script.
<indexurl> is the absolute url to your application's index.php script.
* * * * * /usr/bin/php /var/www/xataface/modules/Email/cron.php /var/www/myapp/index.php http://example.com/myapp/index.php mail
If you want to see what this line should be like for your server, you can simply point your browser to the email_install action of your application (i.e. http://example.com/yourapp/index.php?-action=email_install) and it will generate this line to copy and paste into your crontab. Note that the /usr/bin/php portion of this line may vary according to your environment. It represents the path to your PHP binary.
That's it! You're ready to send email. See the Usage section to see how to send email from your application.
Though the email action may work out of the box, you will likely have to configure it to work the way you want. Some examples of things you will want to configure include:
Limit the email action to only be available for certain tables.
Apply permissions to the action so that only administrators can send email.
Set the name of the column that contains email address (default is 'email').
Change the name of the table that is used to store sent email messages.
Overriding the [email] action
The first thing you need to do to configure the email action is override it in your appliation's actions.ini file. You can do this by adding the following to your actions.ini file:
[email > email]
Now any directives you add in this section will override the email action.
[email > email]
condition="$query['-table'] == 'Pledge' or $query['-table'] == 'User'"
Limiting email action by permission
By default your users require the email permission in order to have access to the email form. This permission is not included with any roles by default so you'll need to extend any roles that you want to have access to the email access and explicitly add the email permission. The exception to this rule is if you have assigned your users the Dataface_PermissionsTool::ALL() permissions in your getPermissions() method.
Suppose you want the READ ONLY role to have access to the email action, you could add the following to your application's permissions.ini file:
[READ ONLY extends READ ONLY]
Changing the name of the email address column
By default, the Email module will try to guess which column contains the email address for a table. Generally it looks for a column named email. You can override this setting to explicitly tell the module which column contains the email address by overriding the email_column directive of the email action in your application's actions.ini file:
[email > email]
email_column = "emailAddress"
=Changing the name of the table that stores the sent email
Xataface automatically stores each sent email for your records. By default it stores these emails in a table named newsletters. You can override this table name with the email_table directive in your application's actions.ini file. This table will be automatically created by Xataface when email is sent out.
Navigate to a table for which your email module is enabled, and click on the list tab.
Click on the "Email" icon in the upper right corner. This should display an email form.
Fill in the email form and press Save.
You should receive a message saying that the email has been queued for delivery. Your cron script will automatically begin sending emails the next time around. So make sure that you have yoru cron script set up properly.
Opting Out of the Email List
If you have received an email that was sent via the email module you can easily opt out of the mailing list by clicking on the link at the end of the email. This link will bring you to a webpage that asks you to confirm that you no longer wish to receive email from this list.
Using a View to add Email Action to Related Record List
You can simulate a many-to-many relationship in a mysql view by creating a view with all possible combinations.
e.g. If you have a Many to Many relationship between books and authors your relationship from the books table might be something like:
__sql__ = "select * from authors a inner join book_authors ab on a.author_id=ab.author_id where ab.book_id='$book_id'"
And your relationship from the authors table would be something like:
__sql__ = "select * from books b inner join book_authors ab on b.book_id=ab.book_id where ab.author_id='$author_id'"
Now if our goal was to be able to send email to all authors of a particular book (i.e. send to the authors relationship), we could create a view:
create view book_authors_maillist as
select * from authors a inner join book_authors ab on a.author_id=ab.author_id