QuickEmail Snippet Tutorial

I could tell you how many hours it takes to develop a MODX extra Transport Package complete with a build script, properties, multiple MODX elements, internationalized strings, error checks, and then fully test it, but you wouldn't believe me. If you use this extra and like it, please consider donating. The suggested donation for this extra is $5.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-commercial extras with a clear conscience.


PayPal

This snippet is for use with MODX Revolution. QuickEmail can be used to send email from inside another snippet, but its primary use is to see if your email is working, and if not, to help diagnose and solve email problems.

Installing QuickEmail for MODX Revolution

Go to System | Package Management on the main menu in the MODX Manager and click on the "Download Extras" button. That will take you to the Revolution Repository (AKA Web Transport Facility). Put QuickEmail in the search box and press Enter. Click on the "Download" button, and when it changes to "Downloaded," click on the "Finish" button. That should bring you back to your Package Management grid. Right click on QuickEmail and select "Install Package." The QuickEmail snippet should now be installed.

Using QuickEmail

This couldn't be much simpler. Create a document in the Manager and put the following code in the Resource Content field:

[[!QuickEmail]]

When you preview the document, you should receive an email at the address you specified when you installed MODX. You can go to System | System Settings the top menu and put emailsender in the search filter to check that address. If you don't receive an email, Change the snippet tag to look like this:

[[!QuickEmail? &debug=`1`]]

Try previewing the document again and look for an error message near the bottom of the screen.

Diagnosing Email Problems

If you see a message that says, "Could not instantiate mail function," it usually means that either your host has the mail() function turned off (many do) or that you are using a localhost install and there is no working mail server. In that case, one option is to use the MODX SMTP Systems Settings so that MODX will send the mail from an SMTP server (e.g., Gmail) where you have an account.

Go to System | System Settings and type SMTP in the search filter, then click on the grid. Set the SMTP settings to the appropriate values for your SMTP account. The following settings will work for Gmail:

SMTP Authentication: Yes
SMTP Connection Prefix: tls
SMTP Hosts: smtp.gmail.com
SMTP Password: yourGmailPassword
SMTP Port: 465
SMTP User: yourGmailUsername
Use SMTP: Yes

Note that Gmail will change all the email from addresses to match your Gmail account and any settings you use in the tag will be ignored. You can have a separate account in Gmail for sending email from your site if you wish. Some sources report that the prefix/port combo should be tls for port 587 and ssl for port 465, but I know that tls/465 has worked for me.

Once you have set the SMTP settings, try previewing your page again. If there are SMTP errors, you will see a detailed account of the Server interaction. Look for any errors and correct the SMTP settings accordingly. A timeout usually means a problem with the port number or failure to set the SMTP prefix. Failure to connect to the host, usually means the SMTP hosts is incorrect or the SMTP prefix is not set correctly. If you've forgotten to set the SMTP authentication, it will remind you. If there is a problem with authentication, either the SMTP username or the SMTP password are incorrect — there's no way to tell which one is the problem.

Sending Email From Inside Another Snippet

You can use the following code to send email from inside another snippet, although it is just as easy to use the MODX mailer. The MODX mailer is also more efficient, because QuickEmail will do a bunch of processing and then call the MODX mailer. Don't try any of the code below until you've made sure your mail system is working using the method described above.

$props = array(
    'debug' => '0',
    'hideOutput' => '0',
    'message' => 'Some Message',
    'subject' => 'Some Subject',
    'to' => 'someone@somewhere.com',
    'fromName' => 'Some Name',
    'emailSender' => 'someone@somewhere.com',
    'replyTo' => 'someone@somewhere.com',
    'html' => '1',
    'failureMessage' => '<br /><h3 style=&quot;color:red&quot;>Mail Failed</h3>',
    'successMessage' => '<br /><h3 style =&quot;color:green&quot;>Mail reported successful</h3>',
    'errorHeader' => '<br />Mail error:',
    'smtpErrorHeader' => '<br />SMTP server report:',
);

$output =  $modx->runSnippet('QuickEmail',$props);
return $output;

Once you have things working, you may want to set 'hideOutput' to '1'. As an alternative, you can modify the $output variable before returning it. If 'hideOutput' is set to '1', there will be no visible output at all from the snippet — it will just send the email.

All of the properties are optional and have reasonable defaults so try just setting 'message', 'subject', and 'to', and see what you get.

Using The MODX Mailer to send email

Since I mentioned it above, here is how you send email using the MODX built-in email function:

$modx->getService('mail', 'mail.modPHPMailer');
$modx->mail->set(modMail::MAIL_BODY, 'Some message');
$modx->mail->set(modMail::MAIL_FROM, 'someone@somewhere.com');
$modx->mail->set(modMail::MAIL_FROM_NAME, 'Your Name');
$modx->mail->set(modMail::MAIL_SENDER, 'you@yourdomain.com');
$modx->mail->set(modMail::MAIL_SUBJECT, 'Some Subject');
$modx->mail->address('to', 'somone@somewhere.com', 'UserName');
$modx->mail->address('reply-to', 'you@yourdomain.com');
$modx->mail->setHTML(true);
$sent = $modx->mail->send();
if ($sent) {
    $output = 'Mail Sent';
} else {
    $output = 'Mail Not Sent';
}
return $output;

 

My book, MODX: The Official Guide - Digital Edition is now available here. The paper version of the book is available from Amazon.

If you have the book and would like to download the code, you can find it here.

If you have the book and would like to see the updates and corrections page, you can find it here.

MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:

  • Installing MODX
  • How MODX Works
  • Working with MODX resources and Elements
  • Using Git with MODX
  • Using common MODX add-on components like SPForm, Login, getResources, and FormIt
  • MODX security Permissions
  • Customizing the MODX Manager
  • Using Form Customization
  • Creating Transport Packages
  • MODX and xPDO object methods
  • MODX System Events
  • Using PHP with MODX

Go here for more information about the book.

Thank you for visiting BobsGuides.com

  —  Bob Ray