Views Mail

Notes on setting up and using Views Mail 6.x.

Installation, Configuration and Sending Mailing

Simplenews is a requirement for installation.  Basically, you need to create a Newsletter series specifically for Views Mail, then create the newsletters you want to be able to send in Views Mail mailings under that series.

1. Install simplenews and views_mail.  Install mimemail if you want your newsletters sent in HTML format.

2. admin->content management->newsletters->newsletters->add: Add a Newsletter series to use for views_mail: admin/content/simplenews/types/add

3. create content->newsletters: Create a newsletter to send using views_mail.  Make sure you tag it as belonging to the Newsletter series you defined in #2 above.
 
4. admin->site configuration->views mail configuration: Go to views_mail settings.  Select the "Default newsletter series" (the one defined in #2 above) and check "Force group e-mail opt-in".  That's all you need for now.  Click on "Save configuration".

5. Now, you need to add a View.

    admin->site building->views->add

    Views Mail View creation checklist:

      a. give the view a simple name, with no spaces or punctuation
      b. be sure to enter "views_mail" as the tag
      c. you only need a "default" display
      d. distinct = yes
      e. your column (field) labels should be unique
      f.  create "exposed filters" to allow more flexibility in email list creation
          1) when filters are exposed, make sure you check "unlock operator" so that the filter is exposed in the url
          2) you must also NOT use AJAX
     g. most important: make sure at least one field in the view consists of e-mail addresses!
      h. If this is a group view, use OGUR: Roles in current group filter.
      i.  If this is a group view, you will also need to call the views_mail page using the group id, as in: "views_mail?gids[]=201".
      j. Also important: The view needs to have a "description".  This is what views mail will use to display it on the initial Views Mail processing screen.  From that point on, it uses the view name.
     k. DO NOT define "Arguments".
     l. Items per page should be unlimited.

    
6. Create a Views Mail mailing:
   
    You should have a new link in your navigation menu titled "Views Mail processing".  Or, just go to:

     views_mail

     To create a views_mail mailing:

     a. Select view to use for the mailing (created in #5), click on "Continue".
     b. Select recipients . Basically, used exposed filters, if present, to make sure that the view you see consists
         of the email addresses to which you want to send this mailing.
     c. Configure mailing.  Select the columns (fields) to use for the "name" and "e-mail" addresses.  Also, enter
         the subject and message for the mailing (if you desire something other than what is in the selected
         newsletter).  You also select when to send the mailing here.
     e. Confirm mailing.  Click on "Confirm and send" if the information on this screen is correct for the mailing
         you desire.

7. When you click on "Confirm and send", the information you've entered will be written to two tables:

    a. views_mail : This contains the subject, message, sender info.
    b. views_mail_schedule : This contains the recipient name and address and date scheduled for sending.

These tables are now exposed to views.

8. Views Mail only sends e-mails during cron runs.  It will send the mailing to all recipients who are scheduled to have their mailings sent at that time.  If you did not select a time period to send, your mailing will be sent at the next cron run after it was created.  If you did select a time period for sending, then your mailing will be sent at the cron run which is equal to or greater than the scheduled send date.

9. When the end-user receives the e-mail, it will have a footer link which allows the user to "Unsubscribe" from these Views Mail mailings.  If he clicks on the link and confirms, his e-mail address will be added to the views_mail_optout table, along with the node id of the newsletter he has opted out from.  Any e-mail address on this list will automatically be exempted from receiving Views Mail mailings.  The only way to resume sending these mailings to this user is to remove his e-mail address from this table.

Permissions

• send views mail
  Send views mail mailings using any newsletter views mail newsletter series.
• send own views mail
  Send views mail mailings using only newsletters that the user has created that are part of the views mail newsletter series.
• administer views mail
  Access views mail settings.
• unsubscribe from views mail
  Unsubscribe (opt-out) of views mail mailings. This permission is required for users to remove themselves from receiving views mail mailings.  If you send to anonymous users (users who do not have accounts on your site), then the anonymous user role should contain this permission.

HTML Mailings

There are two issues with respect to HTML mail and Simplenews.

• MimeMail is used to send all e-mail messages sent by the system in HTML format. 
• When MimeMail is installed, Simplenews newsletters also have an additional setting to send t he newsletter as plain text or HTML. Simplenews requires MimeMail to send in HTML, so if MimeMail is not installed, Simplenews will send newsletters in plain text by default.

Views Mail View Link

A link can programmatically be placed on all views tagged as "views_mail".  This link will transfer the current view (with selected filters) to the "Configure Views Mail mailing" configuration screen automatically.  In order for this to work, you must:

• Tag any view in which you wish this link to appear as a "views_mail" view.
• Do not turn on "Ajax" for any views_mail view. Views Mail needs to see your exposed filters in the URL.
• In "Views Mail" settings, place a check next to "Create Views Mail View link?" setting option.

views_mail_log

The views_mail, views_mail schedule and views_mail_optout tables are now exposed to Views.  You can use Views to create reports of Views Mail activities.  You can make these views accessible from the Views Mail configuration panel by tagging them with as "views_mail_log".  Don't forget to give each of these views a brief "description".

Clear Logs

There is a setting in Views Mail configuration to "Clear Views Mail sent logs".  This will delete all records in the views_mail and views_mail schedule tables for mailings which have already been sent.  This action cannot be undone.

Code Snippet

The following code snippet can be placed in your View footer ("php" input type) in order to create a link that will take you to the views_mail configuration screen with the current view and selected filters. Do NOT use Ajax.  Your filters should be present in the URL in order to be transferred to views_mail.

<?php

$view = views_get_current_view();
$viewname = $view->name;

$link = views_mail_create_link($viewname);

drupal_set_message($link);

?>

Note: This was originally created to insert the  "Views Mail View Link".  This can now be done in Views Mail settings automatically, with no need to manually insert the above snippet.

Filter out people who have received a specific mailing

As per: http://drupal.org/node/426082

The request was made to be able to filter out people who received a specific mailing. The views_mail_scheduled log table contains the e-mails sent, but I have so far been unable to figure out a way to link those e-mail addresses to the source e-mail addresses in the source node (the node you used in your view to create the mailing list in the first place)

So, I figured the best way to handle this was to add another field to the views_mail_scheduled table: recipient_nid. This is the node id of the node from which the recipient_email is derived (if, in fact, it is taken from a node).

So, if you wish to create a view that contains both the source node for your e-mails, and the views_mail_scheduled log of e-mails sent, then you will need to:

a. Include a "node id" field in your view. This will be the node id of the record which contains the e-mail you are selecting for the view.

b. Select this node id field when you "Configure" your Views Mail mailing.

When you do the above, the node id for each e-mail address will be recorded into the views_mail_scheduled log table when the mailing is processed. This will allow you to create a view that can be "filtered" by both the views_mail and views_mail_scheduled log fields.

If your e-mail addresses are not coming from a node, then select "none" for the "node id" field in the "Configure mailing" step.

FAQ

Question: I processed a Views Mail mailing.  I then went back to the views_mail/view screen and all the content from my previous one is in the message section and subject section.

Answer: That's by design.  I use the $_SESSION to store it.  You can argue that we shouldn't do that; but then, if you spend 30 minutes creating a custom message and then make a mistake, you'd argue for it.

That's what the "Confirm" screen is for -- so you have one more chance to verify what is actually going to be sent.

Question: I tried to send a mail but I think the mail never sent, is there a way to see if a mail actually was sent?

Answer: views_mail reports to watchdog when it sends each individual e-mail.  It also reports if there is an error sending.  But, this is from the standpoint of php.  Whether mail is physically sent from your mail server is another issue.  If you are on a unix system, I would look at your maillog log.

Question: OK, so if I check the watchdog and don't see notices for individual mails they are are not sent?

Answer: Yes.

Question: Views Mail only sends e-mails on cron ?

Answer: Yes

Question: Is it possible to actually filter a view and then click on a link that would send to your module's interface with the view preselected, filtered, etc?

Answer: Yes. See the "Views Mail View Link" setting in Views Mail configuration settings.