|If you wish to only allow e-mail addresses at the domain names in
@referers to receive form results, you probably do not need to change this
variable. However, if you get any 'Error: Bad/No Recipient' messages when
running FormMail, you may have to revisit @recipients and make sure you
have correctly listed all domains or configured this variable.|
@recipients is the most important variable you need to configure. It is an
array of regular expressions defining all valid recipients that can be
specified. In order for an e-mail to be sent to the recipient defined in
a form, the recipient e-mail address must match one of the elements in the
For the most simple setup, place any domain name that you wish to send
form results to in the @referers array. Warning: This allows those domains
to also access your FormMail script and utilize it to process their own
forms, but likely this is what you intended anyway. If so, you can leave:
@recipients = &fill_recipients(@referers);
NO, THAT IS NOT WHAT I INTENDED!
Another alternative, then, is to set @recipients equal to the return value
of the fill-recipients function and pass this function all of the domains
to which e-mail may be addressed:
@recipients = &fill_recipients('domain.com',
You are now allowing e-mail to any username (provided it contains only A-Z,
a-z, 0-9, _, - or .) at those three domains.
Similarly, since @recipients is just an array, you could even do:
@recipients = (&fill_recipients('domain.com','sub.domain.com'),
This would allow any recipient at domain.com and sub.domain.com similar
to the previous example, but would also allow your friends otheruser1 and
otheruser2 on otherhost.com to use your FormMail! Of course, you will need
to add otherhost.com into your @referers array if a form is on their host!
HOW DOES THAT WORK?
When the fill_recipients function is called on an array of domain names,
it turns them into regular expressions. These regular expressions will only
allow e-mail messages to go to a recipient with an e-mail address in the
where domain.com is specified in @referers. For any IP addresses
in @referers, the following address formats are valid:
where 192.168.1.1 is the specified IP address in @referers.
What this means in english is that the only valid addresses are those
to usernames that include only letters, numbers, underscores, dashes or
periods and an exact domain name or IP address that was specified in the
@referers array. Depending on your needs, this may be too broad or not
WHAT IF YOU NEED MORE FLEXIBILITY??
The way FormMail validates a recipient address is to check the supplied
recipient(s) in the submitted form against each element in the array
@recipients (which is a list of Perl regular expressions). If any valid
recipients are found, they will receive a copy of the message.
Using the examples of @referers = ('domain.com','192.168.1.1'); and the
default usage of setting @recipients = &fill_recipients(@referers), the
contents of @recipients are now the same as if you had written:
@recipients = ('^[\w\-\.]+\@domain\.com',
What these regular expressions instruct FormMail to do is require that any
e-mail address passed in as a recipient of the form submission match at
least one of those two formats. The following are examples of valid
and invalid recipients for this exact setup:
Last-First@[192.168.1.1], email@example.com, etc.
INVALID: (using these in your form field 'recipient' will trigger error)
Essentially, it only allows A-Z, a-z, 0-9, _, - and . in the local address
area (before the @, represented as [\w\-\.]+ in regular expression speak)
and requires the domain name to match exactly. When mailing to an IP
address, it must be enclosed in .
BUT I NEED TO MATCH MORE CHARACTERS IN THE USERNAME!
Let's say you need to be able to deliver e-mail to an address like:
This requires that the ':' character now be allowed into the portion of
the recipient field before the domain name. You could then modify
@recipients to read:
@recipients = ('^[\w\-\.\:]+\@domain\.com');
BUT BE CAREFUL!!!!
Allowing certain characters could be VERY dangerous, especially if the
characters are: %, <, >, (, ) or any newlines. You can read:
for information on exactly why the % character could be dangerous. And
the document that prompted 1.91 explains why some of the others could
lead to problems:
I ONLY WANT CERTAIN ADDRESSES TO WORK!
Let's say you only want firstname.lastname@example.org to be able to receive
any form submissions. You should then set the @recipients array to:
@recipients = ('^yourself\@yourdomain\.com');
Now the only valid recipient is that one e-mail address.
If there are several, simply do:
@recipients = ('^user1\@yourdomain\.com',
CAN I USE SOMETHING EASIER?
Prior versions of FormMail recommended settings for @recipients like:
@recipients = ('domain.com','192.168.1.1'); OR
@recipients = ('^email@example.com');
The first is bad because it can be easily tricked by submitting a recipient
such as firstname.lastname@example.org. The second is MUCH better,
but since it is used as a regular expression, and '.' can mean ANY
character, a hacker could use joe@somewhereelseXcom to get past a valid
recipient check. This is not a very big deal in most cases.
WHAT IS THIS ^ CHARACTER AND WHY SO MANY \'s??
In regular expressions, the ^ means "beginning of string". By default,
FormMail places a $ at the end of the match, which means "end of string".
By using both ^ and $ in regular expression matching, FormMail can match a
string exactly. You only need to worry about including the ^, which is
STRONGLY recommended for all regular expressions in the array.
The \ character is used to escape a character that otherwise means
something special in regular expressions. For instance, you now see every
'.' being escaped with a '\', as '.' means ANY CHARACTER, whereas '\.'
requires that it match ONLY a period.
If you need a regular expression matching solution even more specific than
the above examples explain, I recommend picking up a book on Perl.