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.
-Allows creation of messages on the fly.
-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.  Even if you will mostly send custom messages created on the
fly (i.e., messages entered at the time the Views Mail view is created), you must 
still create a Views Mail newsletter type, and at least one newsletter.

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.  Also
	leave this unchecked if you wish to enter the subject line of emails
	"on the fly" (i.e., at the time you create the view to send the email).

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 newsletter you wish to send using Simplenews.  Even if you intend 
   to send custom messages created on the fly (i.e., messages entered at 
   the time the Views Mail view is created), you must still create at least 
   one newsletter to use with Views Mail.

     Create Content -> Newsletter issue

     or

     Create Newsletter issue
   
   For "Newsletter" type select the newsletter you created 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.

   In "Newsletter sending options", check "Don't send now".

   If you want this newsletter, or a custom message created using this newsletter, 
   sent in HTML format, you must select "html" as the "Format" in the "Newsletter 
   sending options" fieldset.

   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.
		Newsletter to 
		  send to this 
		  group			: 	Select the Simplenews newsletter you created in Step 1 that
							contains the message you want sent.

		Subject			:	Enter subject for this email.  Leave blank of you wish this 
		                    to be automatically created from newsletter subject line.
		Message			:	Enter message for this email.  Leave blank of you wish this 
		                    to be automatically created from newsletter body.
		Distinct		:	Select "Yes" here. This is used to make sure the message is
		                    sent only to distinct (non-duplicated) recipients.

		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	somebodysysop	1.1.2.1.2.2	-Allows creation of messages on the fly.
24	somebodysysop	1.1	-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	somebodysysop	1.1.2.1	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	somebodysysop	1.1	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	somebodysysop	1.1.2.1	will be used with Views Mail. This will be referred to as your Views Mail
76	somebodysysop	1.1.2.1.2.2	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	somebodysysop	1.1
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	somebodysysop	1.1.2.1	Simplenews Settings step above. It is your default "Views Mail
90			newsletter type".
91	somebodysysop	1.1
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	somebodysysop	1.1.2.1	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	somebodysysop	1.1.2.1.2.2	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	somebodysysop	1.1.2.1
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	somebodysysop	1.1	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	somebodysysop	1.1.2.1	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	somebodysysop	1.1	USING VIEWS_MAIL
172	somebodysysop	1.1.2.1	================
173	somebodysysop	1.1
174	somebodysysop	1.1.2.1.2.2	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	somebodysysop	1.1
179	somebodysysop	1.1.2.1	Create Content -> Newsletter issue
180
181			or
182
183			Create Newsletter issue
184	somebodysysop	1.1
185	somebodysysop	1.1.2.1.2.2	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	somebodysysop	1.1.2.1
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	somebodysysop	1.1
201	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
202	somebodysysop	1.1	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	somebodysysop	1.1.2.1	a) Select "Views mail" as the Views Type. "Nodes per Page" should be set to "0"
207			(No Paging).
208	somebodysysop	1.1	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	somebodysysop	1.1.2.1	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	somebodysysop	1.1
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	somebodysysop	1.1.2.1.2.2	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	somebodysysop	1.1
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	somebodysysop	1.1.2.1	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	somebodysysop	1.1	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	somebodysysop	1.1.2.1	You may also wish to review the issue queue here: http://drupal.org/project/issues/views_mail
262
263	somebodysysop	1.1	-------------- 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	somebodysysop	1.1.2.1	- figure out how to filter views using views_mail_optout table
280	somebodysysop	1.1
281
282			CREDITS
283
284	somebodysysop	1.1.2.1	Huge kudos to KarenS for creating the original version of this module!