| 1 |
// $Id: README.txt,v 2.00 2008/06/09 16:43:31 somebodysysop and KarenS Exp $
|
| 2 |
|
| 3 |
views_mail
|
| 4 |
|
| 5 |
OVERVIEW
|
| 6 |
|
| 7 |
The Views Mail module provides a flexible method for sending messages to
|
| 8 |
list of users created by the Views module.
|
| 9 |
|
| 10 |
This module was originally created by KarenS and modified by somebodysysop.
|
| 11 |
Details here: http://drupal.org/node/134931
|
| 12 |
|
| 13 |
This tool is essentially a smart query builder for building e-mail
|
| 14 |
lists.
|
| 15 |
|
| 16 |
FEATURES
|
| 17 |
|
| 18 |
-Create recipient list using Views to send mass email.
|
| 19 |
-Test mode available.
|
| 20 |
-Installs Views filters for filtering nodes by OG Group and roles.
|
| 21 |
-Can schedule emails for future delivery.
|
| 22 |
-Uses messages created as HTML newsletters in Simplenews module.
|
| 23 |
-Allows creation of messages on the fly.
|
| 24 |
-Places group e-mail opt-out option in user's account.
|
| 25 |
-Option to force e-mail opt-out.
|
| 26 |
-Option to auto-subscribe all new signups to a newsletter.
|
| 27 |
-Option to auto-subscribe all new group members to a newsletter.
|
| 28 |
|
| 29 |
REQUIREMENTS
|
| 30 |
|
| 31 |
Views Mail requires the following modules to already be installed:
|
| 32 |
|
| 33 |
-Views (to create the email lists) http://www.drupal.org/project/views
|
| 34 |
-CCK (for userreference and nodereference) http://www.drupal.org/project/cck
|
| 35 |
-Simplenews (to create the email messages) http://drupal.org/project/simplenews
|
| 36 |
-Mimemail (to send emails in HTML format) http://drupal.org/project/mimemail
|
| 37 |
-Actions* (to schedule future delivery of emails) http://drupal.org/project/actions
|
| 38 |
-Scheduled Actions (to schedule future delivery of emails)
|
| 39 |
http://drupal.org/project/sched_act
|
| 40 |
No 5.x version available yet, so, you'll have to patch the 4.7 version.
|
| 41 |
Details here: http://drupal.org/node/122391
|
| 42 |
|
| 43 |
*You need actions module for the userreference and nodereference modules it supplies.
|
| 44 |
These are necessary to automatically get the email address of the author of a node.
|
| 45 |
|
| 46 |
INSTALLING VIEWS MAIL
|
| 47 |
|
| 48 |
Make sure you have installed the required modules above and configured them.
|
| 49 |
|
| 50 |
Gunzip and untar the Views Mail tarball and place it into your modules
|
| 51 |
folder. Navigate to Admin->Modules and click on Views Mail to intstall.
|
| 52 |
|
| 53 |
Access Control Permissions
|
| 54 |
--------------------------
|
| 55 |
Assign the user you wish to be able to configure Views Mail the 'administer views mail'
|
| 56 |
permission.
|
| 57 |
|
| 58 |
In order to unsubscribe from a newsletter sent by Views Mail, the anonymous user role
|
| 59 |
must have the 'subscribe to newsletters' permission in Simplenews.
|
| 60 |
|
| 61 |
In order to create a newsletter, the role must have the "create newsletter" permission
|
| 62 |
in Simplenews.
|
| 63 |
|
| 64 |
If you wish a role to be able to send *any* Views Mail newsletter, assign it the
|
| 65 |
'send views mail' permission.
|
| 66 |
|
| 67 |
If you wish a role to send only Views Mail newsletters that are created by the user,
|
| 68 |
then assign it only the 'send own views mail' permission.
|
| 69 |
|
| 70 |
Simplenews Settings
|
| 71 |
-------------------
|
| 72 |
Admin-> Content Managment -> Newsletters -> Newsletters Tab -> Add Newsletter Link
|
| 73 |
|
| 74 |
Add a Newsletter type that you will use for creating newsletter issues that
|
| 75 |
will be used with Views Mail. This will be referred to as your Views Mail
|
| 76 |
newsletter type. Even if you will mostly send custom messages created on the
|
| 77 |
fly (i.e., messages entered at the time the Views Mail view is created), you must
|
| 78 |
still create a Views Mail newsletter type, and at least one newsletter.
|
| 79 |
|
| 80 |
Views Mail Settings
|
| 81 |
-------------------
|
| 82 |
Admin -> Site Configuration - > Views Mail Configuration
|
| 83 |
|
| 84 |
Default Newsletter:
|
| 85 |
|
| 86 |
Select the default newsletter type which will contain the
|
| 87 |
newsletter issues you will send with Views Mail. This
|
| 88 |
default newsletter type should have been created in the
|
| 89 |
Simplenews Settings step above. It is your default "Views Mail
|
| 90 |
newsletter type".
|
| 91 |
|
| 92 |
Force group e-mail opt-in:
|
| 93 |
|
| 94 |
When new user signs up, force the group e-mail
|
| 95 |
opt-in to be checked ON. This means the option
|
| 96 |
will NOT appear on the user's registration
|
| 97 |
page but will appear in the user's "My Account"
|
| 98 |
screen. User can uncheck the option after
|
| 99 |
registration is completed.
|
| 100 |
|
| 101 |
Format the subject line of emails?
|
| 102 |
|
| 103 |
When a newsletter is created, the subject line of the resulting email
|
| 104 |
will be prepended with the name of the newsletter group. Simplenews
|
| 105 |
does this by default. Uncheck this box if you want the subject of
|
| 106 |
the email to only contain the title of the saved newsletter. Also
|
| 107 |
leave this unchecked if you wish to enter the subject line of emails
|
| 108 |
"on the fly" (i.e., at the time you create the view to send the email).
|
| 109 |
|
| 110 |
Create Views Mail link?
|
| 111 |
|
| 112 |
When you create a Views Mail newsletter, do you wish
|
| 113 |
to display a link on the bottom of this newsletter
|
| 114 |
which will take you to the Views Mail view you have created?
|
| 115 |
|
| 116 |
Views Mail link URL:
|
| 117 |
|
| 118 |
Enter the URL to the Views Mail view you have created.
|
| 119 |
Do NOT include the ending '/'. Examples:
|
| 120 |
|
| 121 |
myviewsmailview
|
| 122 |
og/emailmembersbyrole
|
| 123 |
http://mywebsite.org/viewsmailview
|
| 124 |
|
| 125 |
Note that you need to have already created this view in order
|
| 126 |
to have the view URL.
|
| 127 |
|
| 128 |
Views Mail link title:
|
| 129 |
|
| 130 |
Enter the title of the link.
|
| 131 |
|
| 132 |
Subscribe all new signups to newsletter:
|
| 133 |
|
| 134 |
Enter here a newsletter id if
|
| 135 |
you want all new signups to be
|
| 136 |
subscribed to this newsletter.
|
| 137 |
|
| 138 |
Groups whose new users are autosubscribed to newsletters:
|
| 139 |
|
| 140 |
Enter here a group id | newsletter id pair
|
| 141 |
if you want all new members to this group
|
| 142 |
to be subscribed to this newsletter.
|
| 143 |
|
| 144 |
Test Settings
|
| 145 |
|
| 146 |
"Email test mode" - Click this on if you want to run
|
| 147 |
in test mode (i.e., no actual emails sent).
|
| 148 |
|
| 149 |
Views Mail Views
|
| 150 |
----------------
|
| 151 |
Admin -> Site Building - > Views - > Default Views
|
| 152 |
|
| 153 |
Views Mail creates a default view:
|
| 154 |
|
| 155 |
View Name : ViewsMailOptOut
|
| 156 |
View Title: Views Mail Opt Out
|
| 157 |
|
| 158 |
This is a view of users who have opted out of Views Mail by clicking on
|
| 159 |
the "unsubscribe" link in a newsletter they have received.
|
| 160 |
|
| 161 |
This view comes from the "views_mail_optout" table which contains only two
|
| 162 |
columns:
|
| 163 |
|
| 164 |
Email address of user who has opted out
|
| 165 |
Node ID of newsletter from which the user clicked on unsubscribe link
|
| 166 |
|
| 167 |
Any email address on this list will NOT be sent a newsletter via Views Mail
|
| 168 |
until it is removed this list. See http://drupal.org/node/270450 for more
|
| 169 |
details.
|
| 170 |
|
| 171 |
USING VIEWS_MAIL
|
| 172 |
================
|
| 173 |
|
| 174 |
1. Create the newsletter you wish to send using Simplenews. Even if you intend
|
| 175 |
to send custom messages created on the fly (i.e., messages entered at
|
| 176 |
the time the Views Mail view is created), you must still create at least
|
| 177 |
one newsletter to use with Views Mail.
|
| 178 |
|
| 179 |
Create Content -> Newsletter issue
|
| 180 |
|
| 181 |
or
|
| 182 |
|
| 183 |
Create Newsletter issue
|
| 184 |
|
| 185 |
For "Newsletter" type select the newsletter you created for Views Mail
|
| 186 |
(see "Simplenews Settings" above). This means that on the node submission
|
| 187 |
form in the "Newsletter:" pulldown menu, you select the Views Mail newsletter
|
| 188 |
type you have previously created.
|
| 189 |
|
| 190 |
In "Newsletter sending options", check "Don't send now".
|
| 191 |
|
| 192 |
If you want this newsletter, or a custom message created using this newsletter,
|
| 193 |
sent in HTML format, you must select "html" as the "Format" in the "Newsletter
|
| 194 |
sending options" fieldset.
|
| 195 |
|
| 196 |
If you have not created a Views Mail newsletter type in "Simplenews Settings", you must
|
| 197 |
first do that. You must also save this newsletter type as the "Default Newsletter"
|
| 198 |
in "Views Mail Settings".
|
| 199 |
|
| 200 |
|
| 201 |
2. Go to views and create a View of the users you wish to send the message to. You can
|
| 202 |
add exposed filters if you wish end-users to be able to customize the view.
|
| 203 |
|
| 204 |
Admin -> Views -> Add View. Don't forget to:
|
| 205 |
|
| 206 |
a) Select "Views mail" as the Views Type. "Nodes per Page" should be set to "0"
|
| 207 |
(No Paging).
|
| 208 |
b) Select at least one field that contains the e-mail address you wish the message
|
| 209 |
to. Otherwise, the message will be sent to the e-mail address of the node
|
| 210 |
author.
|
| 211 |
c) Save the view. When the view is saved, you can use the URL from this view
|
| 212 |
if you wish to create a Views Mail link (see instructions above).
|
| 213 |
|
| 214 |
3. Go to the view you created in Step 2. Click on the "Send Mail" link to open the
|
| 215 |
Views Mail window. You will see these options for sending your email:
|
| 216 |
|
| 217 |
Recipient name : Select the View field to use for the recipient's name.
|
| 218 |
Recipient email : Select the View field to use for the recipient's email address.
|
| 219 |
Newsletter to
|
| 220 |
send to this
|
| 221 |
group : Select the Simplenews newsletter you created in Step 1 that
|
| 222 |
contains the message you want sent.
|
| 223 |
|
| 224 |
Subject : Enter subject for this email. Leave blank of you wish this
|
| 225 |
to be automatically created from newsletter subject line.
|
| 226 |
Message : Enter message for this email. Leave blank of you wish this
|
| 227 |
to be automatically created from newsletter body.
|
| 228 |
Distinct : Select "Yes" here. This is used to make sure the message is
|
| 229 |
sent only to distinct (non-duplicated) recipients.
|
| 230 |
|
| 231 |
If wish to schedule delivery of this email for a future date, you
|
| 232 |
can click on the "Schedule" link:
|
| 233 |
|
| 234 |
Number : The number of time units below to wait before sending this
|
| 235 |
email. Enter a number.
|
| 236 |
Unit : Unit of time for the number entered above. Seconds, Minutes,
|
| 237 |
Hours or Days.
|
| 238 |
|
| 239 |
4. Once you have completed entering the "Send Mail" options in the Views Mail window, click
|
| 240 |
on the "Send" button at the bottom of this window. You will then be given a summary
|
| 241 |
view of all the elments you selected in Step 3 for verification.
|
| 242 |
|
| 243 |
The "Recipient List" is a list of all the email addresses to which Views Mail will
|
| 244 |
attempt to send the selected newsletter.
|
| 245 |
|
| 246 |
If you see a "Reject List", this contains the email addresses of users from the
|
| 247 |
view who have previously unsubscribed from Views Mail. Their email addresses
|
| 248 |
are in the "views_mail_optout" table which you can also view using the default
|
| 249 |
"ViewsMailOptOut" view. Email can not be sent to these addresses until they
|
| 250 |
are removed from this table.
|
| 251 |
|
| 252 |
If all is correct,
|
| 253 |
then click on "Confirm" to send/schedule the email. If not, go back and correct.
|
| 254 |
|
| 255 |
|
| 256 |
DOCUMENTATION
|
| 257 |
|
| 258 |
There currently is no documentation other then this README.txt file and the original
|
| 259 |
discussions we had on creation of the module here: http://drupal.org/node/134931
|
| 260 |
|
| 261 |
You may also wish to review the issue queue here: http://drupal.org/project/issues/views_mail
|
| 262 |
|
| 263 |
-------------- IMPORTANT --------------------------------------------------
|
| 264 |
-------------- IMPORTANT --------------------------------------------------
|
| 265 |
|
| 266 |
If you update Views or any module that uses Views, you MUST MUST MUST
|
| 267 |
go and resubmit the admin/modules page. Views caches information provided
|
| 268 |
by modules, and this information MUST be re-cached whenever an update
|
| 269 |
is performed.
|
| 270 |
|
| 271 |
DRUPAL CANNOT TELL AUTOMATICALLY IF YOU HAVE UPDATED CODE. Therefore you
|
| 272 |
must go and submit this page.
|
| 273 |
|
| 274 |
-------------- TODO ---------------------------------------------
|
| 275 |
|
| 276 |
- set up userreference and nodereference fields to use the name and email
|
| 277 |
of the userreference and nodereference uid
|
| 278 |
- incorporate Token module to handle substitutions
|
| 279 |
- figure out how to filter views using views_mail_optout table
|
| 280 |
|
| 281 |
|
| 282 |
CREDITS
|
| 283 |
|
| 284 |
Huge kudos to KarenS for creating the original version of this module!
|
Parent Directory
| 
Revision Log
| 
Revision Graph