KB / Web Programming / CGI, PHP, and Databases / Announcement Mailing List
From DreamHost
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.
Parent Article
The basics
The basics of the announcement mailing list feature is described at KB / Account Control Panel / Mail :: Announce Lists. If you are interested in learning how to customize the announcement list, read on.
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. 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="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:
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 create an alias?] [how do I set up an autoresponder?]
NOTE: To change the list's e-mail address, you'll have to delete it (the list) and create a new one.
- DomainName: This is the domain name 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. If you do put something here, it should be in the "domain.com" format.
- 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 [how do I do that?]) whenever someone signs up for the mailing list. Plus, you will ALSO get a default email sent to <nobr>unsubbed-ListName@yourdomain.com</nobr> whenever somebody unsubscribes too!
NOTE: To change the list's e-mail address, you'll have to delete it (the list) and create a new one.
- 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) and that your page is being processed as php (probably that means it needs to end in .php).
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.
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.
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.
