BoxLang 🚀 A New JVM Dynamic Language Learn More...

BoxLang Mail Module

v1.0.0+5 BoxLang Modules

⚡︎ BoxLang Module: BoxLang Mail Module

|:------------------------------------------------------:  |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive
|:------------------------------------------------------:  |

This module provides mail sending functionality to Boxlang

Components

This module contributes the following Components to the language:

  • mail - the wrapping component for a mail operation
    • The following attributes are available to the mail component
      • from - Sender email address
      • to - Comma-delimited list of recipient email addresses
      • charset - The character encoding of the email
      • subject - The email subject
      • server - Optional SMTP server address
      • port - Optional SMTP server port
      • username - Optional SMTP username
      • password - Optional SMTP password
      • useSSL - Optional true|false for SMTP Connection
      • useTLS - true|false for SMTP TLS Connection
      • mailerid - The header ID of the mailer
      • mimeAttach - path of file to attach
      • type - MIME type of the email
      • wrapText - Wrap text after a certain number of characters has been reached
      • sign - true|false Whether to sign the mail message - requires keystore, keystorePassword, keyAlias, keyPassword
      • keystore - The location of the keystore (Used when signing)
      • keystorePassword - The password of the keystore (Used when signing)
      • keyAlias - The alias of the private key to use for signing (Used when signing)
      • keyPassword The password for the private key within the keystore (Used when signing)
      • encrypt - true|false Whether to encrypt the mail message - requires recipientCert, encryptionAlgorithm
      • recipientCert - The path to the public key certificate of the recipient (Used when encrypting)
      • encryptionAlgorithm - The encryption algorithm to use (Used when encrypting). One of DES_EDE3_CBC, RC2_CBC, AES128_CBC, AES192_CBC, AES256_CBC
      • debug - true|false Whether to enable debug logging output
  • mailparam - the component which supplies a mail parameter to the operation, such as headers or files
    • The following attributes are available to the mailparam component
      • name - The header name ( if applicable )
      • value - The header value ( if applicable )
      • contentID - The content ID ( optional content id)
      • disposition - The disposition type ( inline or attachment - if applicable )
      • file - The file path of an attachment ( if applicable )
      • fileName - An optional name of the file to be sent as an attachment ( if applicable )
      • type - The media type ( if applicable )
  • mailpart - the component which supplies a message part ( e.g. "text", "html", etc ) to the mail operation
    • The following attributes are available to the mailpart component
      • type - The mime type of the mail part
      • charset - The character encoding of the mail part
      • wrapText - The number of characters to wrap the mail part at

Examples

Simple Email Example ( Script syntax )

mail
    from="[email protected]"
    to="[email protected]"
    subject="Hello from BoxLang Mail!"
{
    writeOutput( "Hello world!" );
}

Email with a single file attachment ( Templating syntax )

<bx:mail
    from="[email protected]"
    to="[email protected]"
    subject="File For You"
    mimeAttach="/path/to/my/file.pdf"
>
Here's a PDF for you!
</bx:mail>

MultiPart with text and html parts, with an attachment ( Templating syntax )

<bx:mail
	from="[email protected]"
	to="[email protected]"
	subject="Mail In Parts"
>

<bx:mailpart type="text">
Hello mail!
</bx:mailpart>

<bx:mailpart type="html">
<h1>Hello mail!</h1>
</bx:mailpart>

<bx:mailparam file="/path/to/my/file.pdf" fileName="PDFForYou.pdf" type="application/x-pdf" />

</bx:mail>

Configuration

Mail server connectivity may be provided either via runtime configuration ( e.g. .boxlang.json ) or via the attributes allowed by the mail component ( see above ). An example configuration is provided below:

{
	"modules": {

		"mail": {
			// An array of mail servers
			"mailServers" : [
				{
					// The SMTP Server
					"smtp": "127.0.0.1",
					// The SMTP Port
					"port": "25",
					// The SMTP Username
					"username": "",
					// The SMTP Password
					"password": "",
					// Whether to use SSL in connection to the SMTP server
					"ssl": false,
					// Whether to use TLS in connection to the SMTP server
					"tls": false,
					// The idle timeout, in milliseconds, for connection to the mail server
					"idleTimeout": "10000",
					// The timeout, in milliseconds before giving up on attempts to connect
					"lifeTimeout": "60000"
				}
			],
			// The default encoding to use for outbound email
			"defaultEncoding" : "utf-8",
			// Whether to enable spooling of mail - when false, mail will be sent immediately
			"spoolEnable" : true,
			// The interval in fractions of seconds to process the spool
			"spoolInterval" : .50,
			// The connection timeout - defaults to null, meaning no connection timeout attempting to connect to the mail server
			"connectionTimeout" : null,
			// The following attributes are used for signing of all outbound emails
			"signMesssage" : false,
			// The signature keystore
			"signKeystore" : null,
			// The signature keystore password
			"signKeystorePassword" : null,
			// The private key alias within the keystore
			"signKeyAlias" : null,
			// The Key password within the keystore
			"signKeyPassword" : null,
			// Whether to enable mail logging
			"logEnabled" : true,
			// The severity level for logging
			"logSeverity" : "ERROR",
			// The time in minutes retain a message in the spool before the message is discarded - defaults to infinite
			"spoolTimeout" : 0,
			//  The time in minutes to try resending email before it is considered bounced - defaults to infinite
			"bounceTimeout" : 0,
			// Optional directory settings for the spool ( Defaults to BoxLang runtime home )
			"spoolDirectory" : "/usr/local/boxlang/mail/unsent",
			"bounceDirectory" : "/usr/local/mail/bounced"
		}
	}
}

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

1.0.0 - 2024-08-08

1.0.0 - 2024-07-11

1.0.0 - 2024-06-27

Added

  • Added encryption and signature support

1.0.0 - 2024-06-13

  • First iteration of this module

$ box install bx-mail

No collaborators yet.
     
  • {{ getFullDate("2024-05-15T00:40:07Z") }}
  • {{ getFullDate("2024-08-08T03:56:24Z") }}
  • 619
  • 967