modules/views_mail/README.txt

// $Id: README.txt,v 2.00 2008/06/09 16:43:31 somebodysysop and KarenS Exp $

views_mail

OVERVIEW

The Views Mail module provides a flexible method for sending messages to
list of users created by the Views module.  

This module was originally created by KarenS and modified by somebodysysop.
Details here: http://drupal.org/node/134931

This tool is essentially a smart query builder for building e-mail
lists. 

FEATURES

-Create recipient list using Views to send mass email.
-Test mode available.
-Installs Views filters for filtering nodes by OG Group and roles.
-Can schedule emails for future delivery.
-Uses messages created as HTML newsletters in Simplenews module.
-Places group e-mail opt-out option in user's account.
-Option to force e-mail opt-out.
-Option to auto-subscribe all new signups to a newsletter.
-Option to auto-subscribe all new group members to a newsletter.

REQUIREMENTS

Views Mail requires the following modules to already be installed:

-Views (to create the email lists) http://www.drupal.org/project/views
-CCK (for userreference and nodereference) http://www.drupal.org/project/cck 
-Simplenews (to create the email messages)  http://drupal.org/project/simplenews
-Mimemail (to send emails in HTML format) http://drupal.org/project/mimemail
-Actions* (to schedule future delivery of emails) http://drupal.org/project/actions
-Scheduled Actions (to schedule future delivery of emails) 
 http://drupal.org/project/sched_act
 No 5.x version available yet, so, you'll have to patch the 4.7 version.
 Details here: http://drupal.org/node/122391

*You need actions module for the userreference and nodereference modules it supplies.
 These are necessary to automatically get the email address of the author of a node.

INSTALLING VIEWS MAIL

Make sure you have installed the required modules above and configured them.

Gunzip and untar the Views Mail tarball and place it into your modules  
folder. Navigate to Admin->Modules and click on Views Mail to intstall.

Access Control Permissions
--------------------------
Assign the user you wish to be able to configure Views Mail the 'administer views mail' 
permission.

In order to unsubscribe from a newsletter sent by Views Mail, the anonymous user role 
must have the 'subscribe to newsletters' permission in Simplenews.

In order to create a newsletter, the role must have the "create newsletter" permission
in Simplenews.

If you wish a role to be able to send *any* Views Mail newsletter, assign it the
'send views mail' permission.

If you wish a role to send only Views Mail newsletters that are created by the user, 
then assign it only the 'send own views mail' permission.

Simplenews Settings
-------------------
Admin-> Content Managment -> Newsletters -> Newsletters Tab -> Add Newsletter Link

Add a Newsletter type that you will use for creating newsletter issues that
will be used with Views Mail.  This will be referred to as your Views Mail
newsletter type.

Views Mail Settings
-------------------
Admin -> Site Configuration - > Views Mail Configuration

Default Newsletter:	

	Select the default newsletter type which will contain the
	newsletter issues you will send with Views Mail.  This
	default newsletter type should have been created in the
	Simplenews Settings step above.	 It is your default "Views Mail 
	newsletter type".

Force group e-mail opt-in:	

	When new user signs up, force the group e-mail 
	opt-in to be checked ON.  This means the option 
	will NOT appear on the user's registration
	page but will appear in the user's "My Account"
	screen.  User can uncheck the option after
	registration is completed.

Format the subject line of emails?

    When a newsletter is created, the subject line of the resulting email 
    will be prepended with the name of the newsletter group. Simplenews
    does this by default.  Uncheck this box if you want the subject of 
    the email to only contain the title of the saved newsletter.

Create Views Mail link?

    When you create a Views Mail newsletter, do you wish 
    to display a link on the bottom of this newsletter 
    which will take you to the Views Mail view you have created?

Views Mail link URL:

    Enter the URL to the Views Mail view you have created. 
    Do NOT include the ending '/'. Examples: 
    
      myviewsmailview
      og/emailmembersbyrole
      http://mywebsite.org/viewsmailview
	
	Note that you need to have already created this view in order
	to have the view URL.
 
Views Mail link title:

    Enter the title of the link.

Subscribe all new signups to newsletter:	

	Enter here a newsletter id if 
	you want all new signups to be 
	subscribed to this newsletter.

Groups whose new users are autosubscribed to newsletters:

	Enter here a group id | newsletter id pair
	if you want all new members to this group
	to be subscribed to this newsletter.

Test Settings

	"Email test mode" -	Click this on if you want to run 
	in test mode (i.e., no actual emails sent).

Views Mail Views
----------------
Admin -> Site Building - > Views - > Default Views

Views Mail creates a default view:
  
  View Name : ViewsMailOptOut	
  View Title: Views Mail Opt Out	
  
This is a view of users who have opted out of Views Mail by clicking on
the "unsubscribe" link in a newsletter they have received.
  
This view comes from the "views_mail_optout" table which contains only two
columns:

  Email address of user who has opted out
  Node ID of newsletter from which the user clicked on unsubscribe link

Any email address on this list will NOT be sent a newsletter via Views Mail 
until it is removed this list.  See http://drupal.org/node/270450 for more
details.

USING VIEWS_MAIL
================

1. Create the message you wish to send using Simplenews.  

     Create Content -> Newsletter issue

     or

     Create Newsletter issue
   
   Save it as the newsletter type you selected for Views Mail (see "Simplenews Settings"
   above). This means that on the node submission form in the "Newsletter:" pulldown menu,
   you select the Views Mail newsletter type you have previously created.

   If you have not created a Views Mail newsletter type in "Simplenews Settings", you must
   first do that.  You must also save this newsletter type as the "Default Newsletter"
   in "Views Mail Settings".

   
2. Go to views and create a View of the users you wish to send the message to.  You can 
   add exposed filters if you wish end-users to be able to customize the view.
    
   Admin -> Views -> Add View.  Don't forget to:
   
   a) Select "Views mail" as the Views Type. "Nodes per Page" should be set to "0"
      (No Paging).
   b) Select at least one field that contains the e-mail address you wish the message
      to. Otherwise, the message will be sent to the e-mail address of the node
      author.
   c) Save the view. When the view is saved, you can use the URL from this view
      if you wish to create a Views Mail link (see instructions above).

3. Go to the view you created in Step 2. Click on the "Send Mail" link to open the
   Views Mail window.  You will see these options for sending your email:

		Recipient name	:	Select the View field to use for the recipient's name.
		Recipient email	:	Select the View field to use for the recipient's email address.
		Subject			:	This is automatically created from newsletter subject line.
		Newsletter to 
		  send to this 
		  group			: 	Select the Simplenews newsletter you created in Step 1 that
							contains the message you want sent.

		Distinct		:	Select "Yes" here. Not sure what this does.

		If wish to schedule delivery of this email for a future date, you 
		can click on the "Schedule" link:

		Number			:	The number of time units below to wait before sending this
							email. Enter a number.
		Unit			:	Unit of time for the number entered above.  Seconds, Minutes,
							Hours or Days.

4. Once you have completed entering the "Send Mail" options in the Views Mail window, click 
   on the "Send" button at the bottom of this window.  You will then be given a summary
   view of all the elments you selected in Step 3 for verification.  
   
   The "Recipient List" is a list of all the email addresses to which Views Mail will
   attempt to send the selected newsletter.
   
   If you see a "Reject List", this contains the email addresses of users from the
   view who have previously unsubscribed from Views Mail.  Their email addresses
   are in the "views_mail_optout" table which you can also view using the default
   "ViewsMailOptOut" view.  Email can not be sent to these addresses until they
   are removed from this table.
   
   If all is correct,
   then click on "Confirm" to send/schedule the email.  If not, go back and correct.


DOCUMENTATION

There currently is no documentation other then this README.txt file and the original
discussions we had on creation of the module here: http://drupal.org/node/134931

You may also wish to review the issue queue here: http://drupal.org/project/issues/views_mail

-------------- IMPORTANT --------------------------------------------------
-------------- IMPORTANT --------------------------------------------------

If you update Views or any module that uses Views, you MUST MUST MUST
go and resubmit the admin/modules page. Views caches information provided
by modules, and this information MUST be re-cached whenever an update
is performed. 

DRUPAL CANNOT TELL AUTOMATICALLY IF YOU HAVE UPDATED CODE. Therefore you
must go and submit this page.

-------------- TODO ---------------------------------------------

- set up userreference and nodereference fields to use the name and email 
  of the userreference and nodereference uid
- incorporate Token module to handle substitutions
- figure out how to filter views using views_mail_optout table


CREDITS

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