modules/views_mail/README.txt

// $Id: README.txt,v 1.24 2007/04/26 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.

Simplenws 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.

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.

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.

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).

USING VIEWS_MAIL

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

   Create Content -> Newsletter.
   
   Save it as the newsletter type you selected for Views Mail.
   
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.
   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.

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			:	Enter the text to be used as the email 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.  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

-------------- 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


CREDITS

Huge kudos to KarenS for creating this module!
1	somebodysysop	1.1	// $Id: README.txt,v 1.24 2007/04/26 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			-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			Simplenws Settings
53			------------------
54			Admin-> Content Managment -> Newsletters -> Newsletters Tab -> Add Newsletter Link
55
56			Add a Newsletter type that you will use for creating newsletter issues that
57			will be used with Views Mail.
58
59			Views Mail Settings
60			-------------------
61			Admin -> Site Configuration - > Views Mail Configuration
62
63			Default Newsletter:
64
65			Select the default newsletter type which will contain the
66			newsletter issues you will send with Views Mail. This
67			default newsletter type should have been created in the
68			Simplenews Settings step above.
69
70			Force group e-mail opt-in:
71
72			When new user signs up, force the group e-mail
73			opt-in to be checked ON. This means the option
74			will NOT appear on the user's registration
75			page but will appear in the user's "My Account"
76			screen. User can uncheck the option after
77			registration is completed.
78
79			Subscribe all new signups to newsletter:
80
81			Enter here a newsletter id if
82			you want all new signups to be
83			subscribed to this newsletter.
84
85			Groups whose new users are autosubscribed to newsletters:
86
87			Enter here a group id \| newsletter id pair
88			if you want all new members to this group
89			to be subscribed to this newsletter.
90
91			Test Settings
92
93			"Email test mode" - Click this on if you want to run
94			in test mode (i.e., no actual emails sent).
95
96			USING VIEWS_MAIL
97
98			1. Create the message you wish to send using Simplenews.
99
100			Create Content -> Newsletter.
101
102			Save it as the newsletter type you selected for Views Mail.
103
104			2. Go to views and create a view of the users you wish to send the message to. You can
105			add exposed filters if you wish end-users to be able to customize the view.
106
107			Admin -> Views -> Add View. Don't forget to:
108
109			a) Select "Views mail" as the Views Type.
110			b) Select at least one field that contains the e-mail address you wish the message
111			to. Otherwise, the message will be sent to the e-mail address of the node
112			author.
113			c) Save the view.
114
115			3. Go to the view you created in Step 2. Click on the "Send Mail" link to open the
116			Views Mail window. You will see these options for sending your email:
117
118			Recipient name : Select the View field to use for the recipient's name.
119			Recipient email : Select the View field to use for the recipient's email address.
120			Subject : Enter the text to be used as the email subject line.
121			Newsletter to
122			send to this
123			group : Select the Simplenews newsletter you created in Step 1 that
124			contains the message you want sent.
125
126			Distinct : Select "Yes" here. Not sure what this does.
127
128			If wish to schedule delivery of this email for a future date, you
129			can click on the "Schedule" link:
130
131			Number : The number of time units below to wait before sending this
132			email. Enter a number.
133			Unit : Unit of time for the number entered above. Seconds, Minutes,
134			Hours or Days.
135
136			4. Once you have completed entering the "Send Mail" options in the Views Mail window, click
137			on the "Send" button at the bottom of this window. You will then be given a summary
138			view of all the elments you selected in Step 3 for verification. If all is correct,
139			then click on "Confirm" to send/schedule the email. If not, go back and correct.
140
141
142			DOCUMENTATION
143
144			There currently is no documentation other then this README.txt file and the original
145			discussions we had on creation of the module here: http://drupal.org/node/134931
146
147			-------------- IMPORTANT --------------------------------------------------
148			-------------- IMPORTANT --------------------------------------------------
149
150			If you update Views or any module that uses Views, you MUST MUST MUST
151			go and resubmit the admin/modules page. Views caches information provided
152			by modules, and this information MUST be re-cached whenever an update
153			is performed.
154
155			DRUPAL CANNOT TELL AUTOMATICALLY IF YOU HAVE UPDATED CODE. Therefore you
156			must go and submit this page.
157
158			-------------- TODO ---------------------------------------------
159
160			- set up userreference and nodereference fields to use the name and email
161			of the userreference and nodereference uid
162			- incorporate Token module to handle substitutions
163
164
165			CREDITS
166
167			Huge kudos to KarenS for creating this module!