Announcement Mailing List

From DreamHost

Jump to: navigation, search

We provide a simple CGI program that visitors to your site can use to subscribe to any mailing lists you offer via a form on your web page.

Instructions on how to use that form as well as common questions regarding its usage are below.

Contents

How to post to mailing list ?

In order to post to an announcement list, visit the posting page. To get there, log into the panel and navigate to Mail > Announce Lists. If you have any active lists setup, you'll see them shown here. To make a new post, click "Mail" underneath the Actions column. On the page that loads, you can compose your announcement using the form.

"From:" - would be which address the announcement is coming from. Usually, this doesn't need to be changed. "Subject:" - what the announcement's about "Your message:" - paste in the message itself, either as plain text, or the HTML source code of an HTML announcement.

"Is this HTML?" - check the box if you pasted HTML code in the message body. If you need help sending messages with HTML formatting, try using a WYSIWYG HTML editor. There are many free online options. Free Online HTML Editor

To schedule the announcement for a future time to send, be sure to edit "Send Announcement At:". Otherwise, it will be queued to begin sending as soon as possible. Click "Submit Announcement Now" if everything is all set and it will be added to the announcement list sending system for queuing (or scheduled.)

Note: It's also possible to post an announcement via the Dreamhost API. Be sure to check the section on Announcement Lists for further details.

How can people subscribe to my mailing list?

You can manually add people to your list from our Announcement List area.. they will receive an email with a link to confirm their subscription.

For the general public all you have to do is put some of the following HTML code in a web page that you host with us. Keep in mind that a lot of these fields can be adjusted for your list by editing it in the webpanel removing the need to manually add them to your form (and in some cases your must use the webpanel for a particular field to work). That's it!

Note: You must customize the fields in red according to your needs. See below for an explanation of these fields. Also, if you have multiple mailing lists, you must have a separate subscription form for each one.


<form method="post" action="http://scripts.dreamhost.com/add_list.cgi">
<input type="hidden" name="list" value="FromEmailAddress" />
<input type="hidden" name="domain" value="DomainName" />
<input type="hidden" name="url" value="http://SubscribedURL" />
<input type="hidden" name="unsuburl" value="http://UnsubscribedURL" />
<input type="hidden" name="alreadyonurl" value="http://AlreadyOnURL" />
<input type="hidden" name="notonurl" value="http://NotOnURL" />
<input type="hidden" name="invalidurl" value="http://InvalidURL" />
<input type="hidden" name="emailconfirmurl" value="http://EmailConfirmURL" />
<input type="hidden" name="emailit" value="1" />
Name: <input name="name" />
E-mail: <input name="email" /><br />
<input type="submit" name="submit" value="Join Our Announcement List" />
<input type="submit" name="unsub" value="Unsubscribe" />
</form>


This code will put the following form on your website:

Sample announcement list form

Visitors to your site subscribe by simply filling in the form! Once someone has subscribed to your mailing list, it will appear in the Web Panel for management and posting to the list.

If you would like your visitors to redirect to a custom page after filling out the form, you can easily configure this in the panel as well.

It is optional to ask people for their name to go with their email address, if you don't want to, just remove this html code to your form: 

 Name:<input name=name>
You can customize the following fields from the subscription code:
  • FromEmailAddress: This is the part of your mailing list "From Email" that comes before the @ sign. So if your list is jokes@domain.com, this would be jokes. You can view all your lists (and their From Email Addresses) on the "" Mail : Mailing List" section of the webpanel. Realize that people won't actually be able to send email to listname@yourdomain.com unless you set that up as an alias and/or auto-responder through the web panel.
    How do I set up an autoresponder?
    How to create an Alias?
  • DomainName: This is the KB_/_Domains_/_All_About_Domain_Names of the site where this form is residing. It's not necessary to have this field, but having it will ensure full compatibility with all browsers.
  • SubscribedURL: Note that this URL must be set by editing your announcement list in the webpanel. This is a full URL of the page that will appear after someone has successfully subscribed to your mailing list. You can create your own .html page to tell people they've subscribed (in which case, the URL would be something like http://www.yourdomain.com/SubscribedURL.html), or you can leave this field blank to have subscribers forwarded to a very bland page telling them that they have subscribed to your list. If you do create a custom page, it should probably tell them that they have successfully subscribed to your list, and where they can go to unsubscribe.
  • UnsubscribedURL: The URL of the page that appears if someone just successfully unsubscribed from the list. You can create your own .html page to tell people they've unsubscribed (in which case, the URL would be something like http://www.yourdomain.com/UnsubscribedURL.html), or you can leave this field blank to have subscribers forwarded to a very bland page telling them that they have unsubscribed from your list.
  • AlreadyOnURL: The URL of the page that appears if someone who is already on the list attempts to subscribe to it. You can create your own .html page to tell people they're already on your list (in which case, the URL would be something like http://www.mydomain.com/already_on.html), or you can leave this field blank to have subscribers forwarded to a very bland page telling them that they are already on your mailing list.
  • NotOnURL: The URL of the page that appears if they are not on the list, and they have attempted to unsubscribe. You can create your own .html page (in which case, the URL would be something like http://www.mydomain.com/not_on.html), or you can leave this field blank to have subscribers forwarded to a default page telling them that they are not on your list.
  • InvalidURL: The URL of the page that will appear if the email address entered is invalid. You can create your own .html page with this message, (in which case, the URL would be something like http://www.mydomain.com/invalid.html), or you can leave this field blank to have subscribers forwarded to a default page with this information.
  • EmailConfirmURL: The URL of the page that will appear when the user confirms their opt-in to your list by clicking a link in an email message just sent to them. If you customized the URL field, you should probably customize this one as well. You basically need a message that says something like "You are not QUITE subscribed yet.. please now check your email right now for the last step to confirm your subscription to our list!". You can create your own .html page with this message, (in which case, the URL would be something like http://www.mydomain.com/emailconfirm.html), or you can leave this field blank to have subscribers forwarded to a default page with this information.
  • emailit: If you have this hidden input in the form, you will automatically receive a default email sent to ListName@yourdomain.com (which you can then set up as an auto-responder whenever someone signs up for the mailing list. Plus, you will ALSO get a default email sent to unsubbed-ListName@yourdomain.com whenever somebody unsubscribes too!
  • Join Our Announcement List: This label can be changed to anything that doesn't contain the words "remove", "out", "unsub", "leave", or "delete," and it will act as the subscribe button. Also if you're an HTML expert you can use an image for the submit button. But we leave that up to you to learn how to do.
  • Unsubscribe: This will be the label on your "unsubscribe" button. It's not mandatory to have this button, but it's more convenient for everyone, if your list members can unsubscribe over the web, without your intervention. The name of this button must include one of the following: "remove", "out", "unsub", "leave", or "delete". If it doesn't, it will act as though it is a subscribe button.

Can I add more fields to the basic form?

Hey, we've got a new feature that allows our mailing list form to double as a formmail script! Basically, any extra fields you add to your form (besides the ones listed above and the three that follow) will be included in the notification email you get when somebody subscribes to your list! You can also now customize that with these three new hidden fields:

  • required: A comma-separated list of fields your user MUST fill in in order to successfully submit the form. Example: <input type=hidden name=required value="street1, city, state, zip, country">
  • missingrequrl: The url to redirect to if somebody tries to submit a form without some of the required fields you specified via the "required" form element. This url will also get posted to it a variable called "missing" with a value like "field1,field2,field3" with all the missing fields. Example: <input type=hidden name=missingrequrl value="http://www.mysite.com/missingrequiredfields.html">
  • fieldorder: A comma-separated list that tells you the order you'd like the fields to be reported to you in the email you receive. If you don't specify this, they will appear in random order (not necessarily the order they appear in your html form). If you do specify this value, you will ONLY receive the fields you list here (plus name and email address, which are always first). Example: <input type=hidden name=fieldorder value="orgname, street1, city, state, zip, country">

How do I make sure email addresses are correct?

Hey, another new feature! So, let's say you don't think your potential subscribers can handle typing their own email address correctly the first time, and you want them to re-type it JUST to be sure there are no mistakes. Easy peasy! Just add:

  • <input type=hidden name=req_address2 value=1 ><input name=address2 >

How do I display information from the form on my custom URLs?

Whoa, another new feature! Now, if you use your own custom URLs for the various results that can come from users submitting this form, you can still get access to some of the information submitted in the form! Our script now redirects to your URLs with the following variables:

  • address=user@domain.com
  • name=Their+Name
  • code=#

Where the codes are as follows:

Address Successfully Subscribed: 1
Address Successfully Unsubscribed: 2
Address Successfully Mailed Confirmation Link: 3
Address Already on List: -1
Address Not In List (when Unsubscribing): -2
Invalid Email Address: -3
Missing Required Field(s): -4
Re-typed email doesn't match first: -5

Following is an example that reads the name and address entered on the form on a custom Subscribe URL response page: 

<?php
$email = $_GET['address'];
$name = $_GET['name'];
?>
Thanks for subscribing, <?php echo $name; ?> - we'll send our next newsletter to you at <?php echo $email; ?>!

This example assumes the name form field is required (otherwise you'd need to get a little fancier to display something else if the name field is blank, look below for one way to handle this problem) and that your page is being processed as php (probably that means it needs to end in .php).

Using a PHP conditional to check for data in the name field:

<?php
if ($name!="") 
echo "$name"; ?>

Thanks for subscribing<?php if ($name!="") echo ", $name"; ?> - we'll send our next newsletter to you at <?php echo $email; ?>!

This way, the name field will not print if it contains nothing.

How do I use images for my subscribe and unsubscribe submit buttons?

If you don't want to use the standard submission buttons but would rather use your own images, you can do that with this code:

<input type="image" border="0" name="submit" src="subscribe.gif"> <input type="image" border="0" name="unsub" src="unsubscribe.gif">

(Instead of this: <input type=submit name=submit value="Join Our Announcement List"> <input type=submit name=unsub value="Unsubscribe">)

How do the members post to the list?

They cannot. This is an announcement-only mailing list, not a discussion list. We also offer discussion lists, however, which are much better suited for this sort of usage.

How can I set it up so everyone who subscribes automatically gets a welcome message?

Just set up ListName@yourdomain.com to be a valid email alias (which can point to null if you don't want to receive an email notifying you each time a new person subscribes), and then set up an auto-responder for that alias! Then make sure you DO have the emailit hidden input in your form on your web page.

Note, we're talking about the announcement-only mailing list here, not the mailman discussion list feature, which has its own configuration to allow a welcome message to be sent to all new subscribers.

How many people can be on my list?

There is no limit on the number of people who can be on a given list.

However, it may take a while for all the messages to go out if you have a really large list (they will go through, eventually, though). If a message you sent hasn't gone out and it's been over six hours, don't resend it. Instead, contact our Support Team and let them know that you think the "mailing list queue needs to be cleared out".

Support will know what to do, and will be able to get all the messages in the outgoing queue to go through. If you had resubmitted your post, two copies will be in the queue at this point, and your subscribers will all get both emails.


How can I import a list from my old list to here?

Create an announcement list from our "Mail > Announcement List"panel. Then click "edit", cut and paste a list of each of the old addresses you had into the "Subscriber List" box there, then click on "Edit Announcement List".

Note, we require that ALL subscribers to ALL announcement lists on our system to have confirmed their intention to subscribe. So, when you paste in this list, you'll first be emailing all of them a message (which you can customize) explaining that you've moved your list provider and will need everybody who wants to keep receiving the list to re-confirm their subscription. They'll just have to click a link in that email to do so!

However, if your old list has already been confirmed using our announcement list software, you can easily migrate your list from that domain to another one on your account. Edit your list in the control panel, and choose the new domain from the drop-down list for your 'List Name'. Don't forget to update your code if you're using a customized subscription form on your site!

How can I export my list here for use elsewhere?

There is not a formalized "export" function available from within the Control Panel, and you can't really "get at" the right files in the shell to manipulate it from there, but a really easy way to "export" the list is to just copy the subscribers list from within the panel.

Once you have done this, you can easily (with a program if you want, or just with a decent editor) "massage" the copied "list" into a CSV ("Character Separated Value") style data file suitable for importing into other programs, a database, spreadsheet, etc.

The general process goes something like this:

1) Go to The Control Panel -> Mail -> Announcement Lists screen in the Control Panel.

2) Click the "Edit" Link in the "Actions" column of the row for the list you want to work with.

3) Scroll down to the "Edit Subscriber List" section, and select what information you want to be displayed. There you will see, "Current Subscriber List (N):" (where "N" is the number of items in the list) followed by links to "Show/hide Dates" and "Show/hide Names" (Depending upon how you last left those items set).

4) Use those links to add (or remove) the display of those items, so that you have the basic "contents" of the list information the way you want it.

5) Move your cursor into the text area and "select" all the text in the box (exact method varies depending upon your os/browser), and "copy" that data.

6) Now you can open an editor on your computer (use a programmers' editor, not a "WordProcessor") and "paste" that copied data into a file. If you only displayed the email addresses - then you are done.

7) If you chose to also display the Names and/or Dates, from this point, you can either execute a couple of "search and replace" operations to "clean-up" your data to put it in the format you want it to be in, or just "save" that file for subsequent processing with another program.

It is easy to use a couple of "mass search and replace" runs to change the extraneous "[name: ", "[joined on ", and "]" characters into field separators (with the last "]" being omitted altogether of course, or changed into the end of line character/s appropriate for your intended use.)

While this is not particularly elegant, it only takes a couple of minutes to do, and you can use whatever file format/character separator you want to delineate the fields this way - so it's almost better than a "canned export" function that might offer less flexibility.


When I manually add subscribers, can I give them names?

You can include names when manually subscribing users from the edit link of our "Mail > Announce List" area!

Just put their names on the same line as their email address in the Emails to Add field, separated by a space. For example: 

person1@domain.com jane doe
person2@domain.com john doe
person3@domain.com john q. public
That's it!


What can I use this list for?

Use your mailing list to keep subscribers up to date on changes to your business or web community. If your site is home to a club, keep subscribers apprised of meetings and events. If you have a business site, you can use the list to send product updates to customers who have requested updates. If your site has a newsletter, you can even use your mailing list to distribute your newsletter to people who have asked for it.

Note that mailing lists are only for mailing those who have specifically signed up to be on this list through your website. You may not send any unsolicited bulk email (also known as "spam") through this service. If you spam, your account may be immediately terminated without warning.

In addition, at the bottom of every mailing, you must put instructions for unsubscribing from the list.

For more details on what you can and cannot do under our anti-spam policy, please read our spam policy and resources page.


Will my mailing list still work if I change my domain's MX record?

Believe it or not, it still will! Nothing will change with it at all, except that if you have an auto-responder set up it will stop working. But you can still post to your list and people can subscribe and unsubscribe as before.

Receiving bounced messages for your mailing list

How do I set up my mailing list so that I get notified when email is bounced from addresses on the list?

In order to get the "bounced" messages for your mailing list, you need to set up an email alias (address) called "listname@domain.com," where these messages can be sent. So, for example, if your list is called "customers," and your domain is "mybiz.com," you need to create an email alias called "customers@mybiz.com."

If you have set up a default email address to catch all incoming email to your domain (except for that mail covered by other addresses you have already created), this should also catch the "bounced" messages, though you might want to set up "listname@domain.com" anyway, just in case.

Also, keep in mind that you have to set the "Remove Bad Addresses" option on your list to "never", or else bounceback messages will go to us directly (and not your email address) so that we can process the bouncebacks automatically for you.

To learn more about aliases and how to set them up, check out the "related links" in the column to the left of this window.

Can I send HTML encoded messages to my list?

Yes you can!

Just click until you see a check mark appear in the little "This is HTML" checkbox next to the submit button on the mail page. This will result in HTML tags in your message being interpreted as HTML for people whose mail clients have HTML capabilities.

You should paste your HTML code directly into the textarea that says "Your message:".

Also, don't worry that some people on your list can't read HTML-formatted email! Your message is sent as a multi-part message.. those who can't read HTML will get a plain text version!

How do I edit my mailing lists?

  1. Go to the Mail > Mailing Lists section of our Account Control Panel.
  2. Click on the Edit link next to the list you'd like to edit.
  3. Change the "from" name or subject field here: File:/images/illustrations/sendfrom.gif
  4. To edit your list of subscribers: File:/images/illustrations/currentsubs.gif
    • Write the email addresses of subscribers to be added in this box (note, on the next page you'll send them an email to confirm their wish to be on your list): File:Images/illustrations/addname.gif
    • Write the email addresses of subscribers to be removed in this box: <img src = "./images/illustrations/removename.gif">
  5. Press the Edit Mailing List button, and you're done!

NOTE: To change the list's e-mail address, you'll have to delete it (the list) and create a new one.

How do I import a CSV file into my mailing list?

When a list of emails is copied into the the "Emails to Add" box on the edit page, it will automatically filter out duplicates. Therefore, if you have an external system which you want to periodically import into Dreamhost's address list, it is fairly simple to create a PHP script that parses the CSV file for the contact's email and, optionally, name and displays the results in a read-only textarea that can simply be copy-pasted directly into Dreamhost's cpanel. 

// Parse the CSV and enter the results into an array
// This process will differ depending on the contents of the CSV
// The function to use is fgetcsv(), see http://ca.php.net/manual/en/function.fgetcsv.php
$contacts = array();

// Loop through each line in the CSV
$temp['email'] = $email; // Read the email column
$temp['name'] = (!is_null($name) && srtlen($name) > 0 && $name != "") ? " ".$name : ""; // Read the name column, set to empty if there is no name
array_push($contacts, $temp);

// In a blank HTML form (action=""), put this:
<textarea rows="10" cols="50" readonly="readonly"><?php foreach($contacts as $contact) {echo $contact['email'].$contact['name']."\n";} ?></textarea>

How do I post to my announcement list?

  1. Log in to the Account Control Panel. Select the Mail tab, and click on the Announcement Lists link.
  2. Click on the Mail link to the right of your list.
  3. Enter a return name and a subject line for your outgoing message. 
File:Images/illustrations/sendfrom.gif
  1. Write or paste the message you wish to send in the large text box.
  2. If your message is HTML-formatted, be sure to click the checkbox marked This is HTML.
  3. Click the Send Message link, and you're done!

The only way to post to an announcement list is through this form.. if you want an open discussion style email list, what you need are our discussion lists!

What is a charset?

When you send an announcement or auto-responder (for both html or plain text emails), you now have the option to choose a character set for the text encoding other than Western European (iso-8859-1).

You will need to specify a character set if you're emailing in languages that use characters outside the normal ASCII range. Languages like Chinese, Arabic, Hebrew, Japanese, Russian, etc..

Just enter the encoding type (you'll have to know it yourself!) you want into the text box provided and be sure to check off the "this is html" option (and to actually use html to mark-up your message!) before clicking "Send Message!"

See also

Retrieved from "http://wiki.dreamhost.com/Announcement_Mailing_List"
Personal tools