Email Library

revIgniter's robust Email Library supports the following features:

• Two Protocols: Sendmail, and SMTP (deprecated “mail” protocol removed)
• Multiple recipients
• CC and BCCs
• HTML or Plaintext email
• Attachments
• Word wrapping
• Priorities
• BCC Batch Mode, enabling large email lists to be broken into small BCC batches.
• Email Debugging tools

Sending Email

Sending email is not only simple, but you can configure it on the fly or set your preferences in a config file.

Here is a basic example demonstrating how you might send email. Note: This example assumes you are sending the email from one of your controllers.

rigLoaderLoadLibrary "Email"

rigMailFrom "your@example.com", "Your Name"  
rigMailTo "someone@example.com"
rigMailCC "another@another-example.com"
rigMailBcc "them@their-example.com"

rigMailSubject "Email Test"
rigMailMessage "Testing the email library."

put rigMailSend() into tMailResult

put rigPrintMailDebugger() into gData["mailDebug"]

Setting Email Preferences

There are 17 different preferences available to tailor how your email messages are sent. You can either set them manually as described here, or automatically via preferences stored in your config file, described below:

Preferences are set by passing an array of preference values to the email rigInitializeMail handler. Here is an example of how you might set some preferences:

put "sendmail" into tConfig["protocol"]
put "/usr/sbin/sendmail" into tConfig["mailpath"]
put "iso-8859-1" into tConfig["charset"]
put TRUE into tConfig["wordwrap"]

rigInitializeMail tConfig

Note: Most of the preferences have default values that will be used if you do not set them.

Setting Email Preferences in a Config File

If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called email.lc, add the Config array in that file. At the end of the file write: rigRunInitialEmailConfig yourArrayVariableName. Then save the file at config/email.lc and it will be used automatically. You will NOT need to use the rigInitializeMail handler if you save your preferences in a config file. Example:

local sEmailConf

put "sendmail" into sEmailConf["protocol"]
put "/usr/sbin/sendmail" into sEmailConf["mailpath"]
put "iso-8859-1" into sEmailConf["charset"]
put TRUE into sEmailConf["wordwrap"]

rigRunInitialEmailConfig sEmailConf

Email Preferences

The following is a list of all the preferences that can be set when sending email.

Email Handler Reference

rigMailFrom

Sets the email address and name of the person sending the email:

rigMailFrom "you@example.com", "Your Name"

Note:  Since the behavior of double dash in shell commands used to send emails has changed it is preferred to not set the sender address if you set the protocol to mail. Using this setting the sender field appears as "<username@domain.com>" in default configurations. It's the account name and host name of the sending user.

rigReplyTo

Sets the reply-to address. If the information is not provided the information in the "mailFrom" handler is used. Example:

rigReplyTo "you@example.com", "Your Name"

rigMailTo

Sets the email address(s) of the recipient(s). Can be a single email, a comma-delimited list or an array:

rigMailTo "someone@example.com"

rigMailTo "one@example.com,two@example.com,three@example.com"

put "one@example.com" into tList[1]
put "two@example.com" into tList[2]
put "three@example.com" into tList[3]

rigMailTo tList

rigMailCC

Sets the CC email address(s). Just like the "mailTo", can be a single email, a comma-delimited list or an array.

rigMailBcc

Sets the BCC email address(s). Just like the "mailTo", can be a single email, a comma-delimited list or an array.

rigMailSubject

Sets the email subject:

rigMailSubject "This is my subject"

rigMailMessage

Sets the email message body:

rigMailMessage "This is my message"

rigSet_altMessage / rigSet_sAltMessage

Sets the alternative email message body:

rigSet_altMessage "This is the alternative message"

This is an optional message string which can be used if you send HTML formatted email. It lets you specify an alternative message with no HTML formatting which is added to the header string for people who do not accept HTML email. If you do not set your own message revIgniter will extract the message from your HTML email and strip the tags.

rigClearMail

Initializes all the email variables to an empty state. This handler is intended for use if you run the email sending function in a loop, permitting the data to be reset between cycles.

repeat for each key tName in tList
  put tList[tName] into tAddress

  rigClearMail
  
  rigMailTo tAddress
  rigMailFrom "your@example.com"
  rigMailSubject "Here is your info" && tName
  rigMailMessage "Hi" && tName && "Here is the info you requested."
  put rigMailSend() into tMailResult
end repeat

If you set the parameter to TRUE any attachments will be cleared as well:

rigClearMail TRUE

rigMailSend()

The Email sending function. Returns boolean TRUE or FALSE based on success or failure, enabling it to be used conditionally:

if rigMailSend() is not TRUE then
  -- Generate error
end if

rigMailAttach

Enables you to send an attachment. Put the file path/name in the first parameter. Note: Use a file path, not a URL. For multiple attachments use the function multiple times. For example:

rigMailAttach "/path/to/photo1.jpg"
rigMailAttach "/path/to/photo2.jpg"
rigMailAttach "/path/to/photo3.jpg"

put rigMailSend() into tMailResult

rigPrintMailDebugger()

Returns a string containing any server messages, the email headers, and the email messsage. Useful for debugging.

Overriding Word Wrapping

If you have word wrapping enabled (recommended to comply with RFC 822) and you have a very long link in your email it can get wrapped too, causing it to become un-clickable by the person receiving it. revIgniter lets you manually override word wrapping within part of your message like this:

The text of your email that
gets wrapped normally.

{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

More text that will be
wrapped normally.

Place the item you do not want word-wrapped between: {unwrap} {/unwrap}