Any PHP developer knows that is is relatively simple to send out emails using PHP. However, there are some things that are kind of hard to do using the built in PHP mail() function. Things like sending attachments or sending HTML emails with an alternate plain text version of the email. Well, the good news is that you can do all of these things with VConsole. There are several PHP functions that can be used for validating email addresses, and sending email messages. Here is a list of those functions and what they do.

Checking Email Addresses for Correctness
The following PHP functions are used to check an email address for correctness.

• check_email() - This PHP function checks an email address to see that it is valid and then returns true or false depending on what it finds. Also, an error message is set if the validation fails. This function is called like this:
  • $valid = check_email($email_address, $error, $dnscheck);
    • $email_address - This should be set to the email address that you want to check. If the email address specified here is not a valid email address, then false is returned otherwise true is returned.
    • $error - This is a variable reference. If the email address is not valid, this variable will be set to the error message that tells you why validation failed.
    • $dnscheck - (Optional) Set this to true or false. If set to true, (default) then DNS is checked for a valid MX or A record for the domain part of the email address. This argument is ignored if the EMCHKOFF parameter is set to 1 (See below). Set to false if VConsole is not connected to the internet.
       
• check_email_domain() - This PHP function checks the first argument to make sure that it ends with @domain and that the domain is a valid domain name. It returns true or false depending on what if finds. Also, an error message is set if the validation fails. This function is called like this:
  • $valid = check_email_domain($address, $error, $dnscheck);
    • $address - This should be set to either an email address or @domain. (Only the @domain part is checked.) If the domain name is valid, then true is returned otherwise false is returned.
    • $error - This is a variable reference. If the domain specified is not valid, this variable will be set to the error message that tells you why validation failed.
    • $dnscheck - (Optional) Set this to true or false. If set to true, (default) then DNS is checked for a valid MX or A record for the domain. This argument is ignored if the EMCHKOFF parameter is set to 1 (See below). Set to false if VConsole is not connected to the internet.
       
• Disabling DNS Checking.
  By default, DNS checking is enabled for the functions above. This is usually a good thing as this prevents any fake email domains from passing email checks. Basically, the domain part of the email address must have a valid MX or A record in global DNS in order for validation to succeed. However, there are some disadvantages to this default behavior. First, DNS lookups take time. If speed is an issue, then you may want to disable DNS checking. Also, if VConsole is not connected to the internet, then you will definitely want to disable DNS checking because DNS checking requires a valid connection to the internet. There may be other reasons to disable DNS checking, but these are the 2 main reasons. So how do you disable DNS checking? Simply set the EMCHKOFF parameter to 1. Open up the vc_console-params table, Look for the record that has the name field set to EMCHKOFF, and then set the corresponding value field to 1. You can also login to VConsole as a full system administrator and disable DNS checking by clicking on Main Menu - Global Settings - Email Settings.

Sending Email
The following PHP functions are used for sending email.

• send_email() - This PHP function sends an email. There are several arguments that control how it works. Email can be sent using the regular PHP mail() function or it can be sent using an SMTP server. By default, this function sends email using the PHP mail() function. To set it to use an SMTP server, you must make the proper changes in the vc_console-params table. We will go over the parameters in this table below in the section: "Sending Email Using an SMTP Server". Also, for security purposes, all email addresses that are passed to the send_email() function must pass the check_email() email validation function. This function is called as follows:
  • send_email($to, $subject, $body, $from, $fromname, $altbody, $html, $attach);
    • $to - This should be either an email address to send to or an array of email addresses to send to. If it is an array of email addresses, multiple emails are sent out.
    • $subject - This should be set to the subject of the email.
    • $body - This should be set to the main body of the email. If this is in HTML, then set the $html argument to true.
    • $from - (Optional) This should be set to the from email address.
    • $fromname - (Optional) This should be set to the plain text name of the person sending the email.
    • $altbody - (Optional) This should be set to a plain text alternate message body. This is usually used if the email is in HTML and you want to provide a plain text alternative for older mail clients.
    • $html - (Optional) This should be set to true or false. Set to true if the message in $body contains HTML code. Set to false if $body only contains plain text.
    • $attach - (Optional) This should be set to the file path of a document to attach or it could be an array of documents to attach to the email. (The document(s) must exist on the server)
       
• send_stationary() - This PHP function works almost like the send_email() function, except that it will send a formatted email using the stationary HTML template file. This allows you to modify the stationary HTML template file so that you can easily send out emails that have the same look and feel. Simply edit the stationary HTML file to match the look / feel that you want in your outgoing emails and every time you call this function, your emails are sent out using the stationary file. So now all your emails can be branded with your logo, they can have a disclaimer, etc... without having to specify all of that every time you send an email. This function actually calls the send_email() function in order to send email. To edit the look / feel of the stationary file, please edit vconsole/skins/vsource/templates/mailtemplate.html  This function is called as follows:
  • send_stationary($to, $subject, $body, $from, $fromname, $altbody, $noreply, $attach);
    • $to - This should be either an email address to send to or an array of email addresses to send to. If it is an array of email addresses, multiple emails are sent out.
    • $subject - This should be set to the subject of the email.
    • $body - This should be set to the body of the email in HTML format.
    • $from - (Optional) This should be set to the from email address.
    • $fromname - (Optional) This should be set to the plain text name of the person sending the email.
    • $altbody - (Optional) This should be set to a plain text alternate message body for those older email clients that do not support HTML
    • $noreply - (Optional) This should be set to either true or false. It defaults to false. If set to true, then a "Do Not Reply" message is added to both the $body and $altbody arguments. (Try setting this to true to see the results)
    • $attach - (Optional) This should be set to the file path of a document to attach or it could be an array of documents to attach to the email. (The document(s) must exist on the server)
       
• Sending Email Using an SMTP server.
  By default, emails that are sent using the send_email() and send_stationary() functions are sent using the default PHP mail() function. If you would rather have emails sent out using an SMTP server, you can do it by setting the correct parameters in the vc_console-params table. Below is a list of the settings to set. Simply open up the vc_console-params table, look for the record that has the name field set to the parameter that you want to change from the list below, and set the corresponding value field.
  • USESMTP - Set the value field to 1
  • SMTPSERVER - Set the value field to the hostname of the SMTP server to use for sending out emails.
  • SMTPUSER - Set the value field to the SMTP username to use for SMTP authentication. (Leave blank if authentication is not needed)
  • SMTPPASS - Set the value field to the SMTP password to use for SMTP authentication. (Leave blank if authentication is not needed)
  • SMTPPORT - Set the value field to the SMTP port to use for sending email. (Usually port 25)
    
    NOTE: You can also set the SMTP server settings by logging into VConsole as a full system administrator and clicking on Main Menu - Global Settings - Email Settings