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	// $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!