Custom form to subscribe or unsubscribe to an Announcement List

Subscribe / unsubscribe form

Instead of manually adding users, you can create an HTML form similar to the one below.

The following items can be adjusted from your list's 'Edit' page so you don't need to manually add them to your form:

  • Unsubscribe URL
  • Already Subscribed URL
  • Not Subscribed URL
  • Invalid Email Address URL
  • Confirmation URL

When someone subscribes through this custom form, an email confirmation is sent displaying your SubscribedURL page (or a generic page if none is specified). For example:


When the recipient confirms by clicking the link in the email, the script will show the EmailConfirmURL page (or a generic page if none is specified).

If any problems occur, the script shows one of the error pages, or the UnsubscribedURL page if the person is unsubscribing.

Form example

Here is a basic form that includes all the optional fields. Note that you must customize the text between underscore ("_") characters (such as _MailingListName_) 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="">
<table><input type="hidden" name="list" value="_MailingListName_" />
<input type="hidden" name="domain" value="_DomainName_" />

<!-- Optional: -->
<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" />
<tr><td>Name</td><td><input type="text" name="name" /></td></tr>
<!-- Required: --> <tr><td>E-mail</td><td><input type="text" name="email" /></td></tr>
<!-- Optional: --> <tr><td>Confirm E-mail</td><td><input type="text" name="address2" /></td></tr> <!-- Required: --> <tr><td><input type="submit" name="submit" value="_Join Our Announcement List_" /></td><td></td></tr> <!-- Optional: --> <tr><td><input type="submit" name="unsub" value="_Remove from list_" /></td><td></td></tr> </table> </form>

Explanation of the fields above

Field Explanation
_MailingListName_ This is the part of your mailing list "From Email" that comes before the @ sign. So if your list is, this would be mylist. Please note that people won't actually be able to send email to unless you set that up as an independent email address or auto-responder in the panel.
_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.
_http://UnsubscribedURL_ The URL of the page that appears if someone successfully unsubscribed from the list. You can create your own .html page or omit this field from the HTML form. If omitted, the value in the Unsubscribe URL field on the Announcement List edit page will be used instead.
_http://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 or omit this field from the HTML form. If omitted, the value in the Already Subscribed URL field on the Announcement List edit page will be used instead.
_http://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 or omit this field from the HTML form. If omitted, the value in the Not Subscribed URL field on the Announcement List edit page will be used instead.
_http://InvalidURL_ The URL of the page that will appear if the email address entered is invalid. You can create your own .html page or omit this field. If omitted, the value in the Invalid Email Address URL field on the Announcement List edit page will be used instead.
_http://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, or omit this field. If omitted the Confirmation URL field on the Announcement List edit page will be used instead.
<input type="hidden" name="emailit" value="1" /> If you have this hidden input in the form, you will automatically receive a default email sent to You can then set this up as an auto-responder whenever someone signs up for the mailing list. Plus, you will also get a default email sent to whenever somebody unsubscribes as well.
_Join Our Announcement List_ This label can be changed to anything that doesn't contain the words "remove", "out", "unsub", "leave", or "delete," and will act as the subscribe button. Also if you're an HTML expert you can use an image for the submit button.
_Remove from list_ This will be the label on your "unsubscribe" button. It's not mandatory to have this button, but it's more convenient 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.

A note for WordPress sites

If your site uses WordPress, you must link to the default "Ugly" permalink type (of the form "") even if you use any of the "Pretty" permalinks instead. This is because the mailing list scripts automatically add parameters to the URLs which don't work with "Pretty" permalinks. If you edit a post or a page, you can find the post ID number in the URL line after the post= text. For example, you might see something like:"edit", so the post ID is "3141". In this example, you would use something like: as the URL of the page even if it also has a "Pretty" permalink like: You may also create these pages outside WordPress to avoid the problems with permalinks.

Can I add more fields to the basic form?

Yes. Any extra fields you add to your form are included in the notification email you get when somebody subscribes to your list. You can also customize that with these hidden fields:

Input name Example Explanation
required <input type=hidden name=required value="street1, city, state, zip, country"> A comma-separated list of fields your user is required to fill in in order to successfully submit the form.
missingrequrl <input type=hidden name=missingrequrl value=""> 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 above. This URL will also get posted to it a variable called "missing" with a value like "field1,field2,field3" with all of the missing fields.
fieldorder <input type=hidden name=fieldorder value="orgname, street1, city, state, zip, country"> 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).
req_address2 <input type=hidden name=req_address2 value=1 ><input name=address2> You can add a field to ensure that the user filling out the form fills it out with their correct email address. The user will need to type their email address once, then re-type it again to be certain it’s correct.

How do I display information from the form if I use custom URLs?

If you use your own custom URLs in the 'optional' section of the form, you can still access some of the information submitted in the form. The DreamHost script now redirects to your URLs with the following variables:

  • 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

The following example reads the name and address entered on the form on a custom Subscribe URL response page:

$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 you're using a PHP file and 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.

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

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 does not print if it contains nothing.

If you need to suppress these query variables (e.g., if you are using WordPress), you can do so by adding the nourlvars=1 query variable when adding someone to the list.

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">

See also


Did this article answer your questions?

Article last updated PST.