TARGET_EMAIL Setting

EMAIL_NAME Index EMAIL_ADDRS

This page documents the TARGET_EMAIL configuration setting in FormMail.

Type Of Setting

TARGET_EMAIL is a MANDATORY setting, which means...

MANDATORY : you *must* modify this setting for your system. FormMail will not work if you don't set the value correctly.

Précis

Valid email addresses.

Description

Set TARGET_EMAIL to a list of patterns that specify which email addresses your forms are allowed to send email to; this is a critical security mechanism and prevents relaying.

Relaying is where an unauthorized person uses your server to send email to anyone in the world.

By setting TARGET_EMAIL to a set of valid email addresses, relaying is prevented.

FormMail will not send email from your forms until you set TARGET_EMAIL to allow the email addresses you want.

Version 9

This page has been updated for version 9 (and later) of FormMail. This means EMAIL_NAME is accessed as a variable - "$EMAIL_NAME". If you are using FormMail version 8, replace all uses of "$EMAIL_NAME" with "EMAIL_NAME".

TARGET_EMAIL is a PHP Array

TARGET_EMAIL is an array. This means it can contain many "elements". Each element is a string (a set of characters in quotes). To create many elements, you simply list the strings separated by a comma.

For example:

$TARGET_EMAIL = array("String 1","String 2","String 3");

You can put a newline after each comma, to make it more readable. Like this:

$TARGET_EMAIL = array("String 1",
      "String 2",
      "String 3");

If you look at the default setting below, you may be wondering why you can see the following:

$EMAIL_NAME."@yourhost\.com$"

and that's not a string!

It's a PHP string concatenation or appending process. EMAIL_NAME is a string (and you can read about it here), and the "." after it says "append the following string to EMAIL_NAME and make one larger string".

So,

$EMAIL_NAME."@yourhost\.com$"

becomes the string:

"^[-a-z0-9.]+@yourhost\.com$"

TARGET_EMAIL uses Patterns

You might be thinking: what are all the \ ^ $ and other punctuation characters?

The strings you need to enter into TARGET_EMAIL contain "patterns". We won't go into patterns here (it's a large subject), but we will explain a few important things:

^	means the beginning; we want email user names to match only at the beginning of the input, so that's why EMAIL_NAME starts with ^, and any email address you add to TARGET_EMAIL should begin with ^.
.	(dot or period) - matches any single character.
\	stops the following character from being a pattern matcher.
$	matches the end.

So, when you want to match ".com", you need to enter "\.com". Otherwise, ".com" would match "Xcom", "Ycom", "xcom", etc., as well as ".com". The "\." says match only ".".

Also, if your server is "yourhost.com", you don't want to match "yourhost.com.anythingelse", so we put "yourhost\.com$" to match the end.

Note: if you're going to send to a domain that you don't own (e.g. yahoo.com or hotmail.com), *DO NOT* use the EMAIL_NAME feature. If you do, then your installation of FormMail could become a spam gateway! Instead, specify exact email addresses using one of the examples below.

For security purposes, it's best to include ^ at the start and $ at the end of all email address patterns. This will prevent spammers from exploiting certain vulnerabilities that may exist in your server's software.

Finally, don't use your AT_MANGLE characters here. The strings in TARGET_EMAIL need to look like real email addresses or email address patterns. You must use "@". Don't worry, spammers can't see inside formmail.php so they can't get the email addresses or patterns you put in TARGET_EMAIL.

Default Value

$TARGET_EMAIL = array($EMAIL_NAME."@yourhost\.com$");

NOTE: this is a placeholder. FormMail will not work with your forms using this default setting. You must replace the TARGET_EMAIL value with a value appropriate for your forms.

Examples

Use the following examples to find what you need for your requirements.

If you only have one host or domain name: replace "yourhost" with the name of your email server computer. For example,
```
$EMAIL_NAME."@yourhost\.com$"
```
becomes:
```
$EMAIL_NAME."@microsoft\.com$"
```
If you work for Microsoft (microsoft.com).
If you have a domain name other than ".com": replace "yourhost\.com" with your email server's full domain name. For example,
```
$EMAIL_NAME."@yourhost\.com$"
```
becomes:
```
$EMAIL_NAME."@apache\.org$"
```
If you work for the Apache organisation (apache.org).
Another example is:
```
$EMAIL_NAME."@rootsoftware\.com\.au$"
```
If you work for Root Software in Australia (rootsoftware.com.au).

If you want to allow email to several domains, you can do that too. Here's an example. At Root Software, our forms can send to any of the following domains:

rootsoftware.com 
    rootsoftware.com.au 
    ttmaker.com 
    timetabling.org 
    timetabling-scheduling.com 
    tectite.com

To achieve this, we have the following setting:

$TARGET_EMAIL = array($EMAIL_NAME."@rootsoftware\.com$",
        $EMAIL_NAME."@rootsoftware\.com\.au$",
        $EMAIL_NAME."@ttmaker\.com$",
        $EMAIL_NAME."@timetabling\.org$",
        $EMAIL_NAME."@timetabling-scheduling\.com$",
        $EMAIL_NAME."@tectite\.com$"
        );

If you want to accept email to several specific email addresses, that's fine too. Here's an example:

$TARGET_EMAIL = array("^russell\.robinson@rootsoftware\.com$", 
    "^info@ttmaker\.com$", 
    "^sales@timetabling\.org$", 
    "^webmaster@timetabling-scheduling\.com$"
    );

or just one email address:

$TARGET_EMAIL = array("^russ-robinson@rootsoftware\.com$");

If you're using an INI file to define your email addresses, then you can and should set $TARGET_EMAIL to an empty value. Like this:
```
$TARGET_EMAIL = array();
```