Getting started with MailerQ 5.6

MailerQ runs on Linux. To get MailerQ up and running on your own computer or on a server you need to take a couple of simple steps:

Download and install MailerQ
Download and install RabbitMQ
Fetch a license file (trial or commercial)

To make this very simple, we have made a quick start to download and install MailerQ.

MailerQ comes with a web based management console that you can use to monitor exactly what is happening, and to adjust all your delivery settings.

Latest News & updates

Contact MailerQ

De Ruijterkade 112

1011 AB Amsterdam

+31 (0)20 520 61 90

info@mailerq.com

Setting	Description
download-blacklist	IP addresses from which no resources can be downloaded
download-cache	Address of the cache (Used in ResponsiveEmail)
download-ttl	Max time to keep downloaded resources in the cache (Used in ResponsiveEmail)
download-whitelist	Exceptions to the download-blacklist
cluster-address	Address for a cluster to share between instances
cluster-exchange	Set cluster exchange
cluster-timeout	Number of seconds the --list-cluster option waits
cluster-verify	Should the server certificate be verified (only used for amqps:// connections)
database-address	Relational database for config data and delivery settings
database-threads	Number of threads to use for DNS lookups for DKIM keys in the database when data is refreshed
database-ttl	Time to live: Database reload interval (Default 600s)
database-validate	Check and fix database settings on startup
download-log-format	Download log format
download-log-file	Download log filename
download-proxy	Route outgoing download requests through a proxy
dsn-advertise	Toggle announcement about DSN extension and parameters
dsn-notify	Events that trigger a notify
dsn-ret	Send full mail (FULL) or headers (HDRS) for notifications
dns-threads	Number of threads used for DNS lookups
dns-getaddrinfo	Whether the MailerQ resolver should rely on getaddrinfo() library calls
dns-min-ttl	Minimum TTL to respect when doing domain lookups
error-log	Full path to the error log
heartbeat-enabled	Toggle user statistics (default: true)
license	MailerQ license file
lock	Process ID for MailerQ instance to prevent from starting instances more than once
max-attempts	Maximum attempts to deliver email
max-delivertime	Maximum time spent trying to deliver email
plugin-directory	Directory with MailerQ plugins
proxy-server	Setup proxy for outgoing HTTP requests
rabbitmq-address	Location and authentication to connect to RabbitMQ
rabbitmq-consumers	Amount of consumer threads (default: 1)
rabbitmq-declare	Enable or disable checking and declaring the queues on startup
rabbitmq-dsn	Your RabbitMQ delivery status notification queue
rabbitmq-durable	Durable/not durable RabbitMQ queues (default: true)
rabbitmq-encoding	Choose encoding for messages (such as gzip)
rabbitmq-exchange	RabbitMQ exchange
rabbitmq-failure	Your RabbitMQ failure queue
rabbitmq-inbox	Your RabbitMQ inbox queue
rabbitmq-local	Your RabbitMQ local queue
rabbitmq-lazy	Lazy/non lazy RabbitMQ queues (default: non-lazy)
rabbitmq-maxpriority	Enable the use of priority queues
rabbitmq-qos	Set a maximum number of messages simultaneously consumed per consumer thread
rabbitmq-flush-qos	Set a maximum number of messages simultaneously consumed during flush
rabbitmq-outbox	Your RabbitMQ outbox queue (must be unique if multiple instances of MailerQ are used)
rabbitmq-persistent	Persistent/not persistent RabbitMQ queues (default: false)
rabbitmq-publishers	Amount of publisher threads (default: 1)
rabbitmq-queues	Names of the RabbitMQ queues to manage email (inbox, failures, retries, etc...)
rabbitmq-refused	Your RabbitMQ refused queue
rabbitmq-reports	Your RabbitMQ report queue
rabbitmq-results	Your RabbitMQ result queue
rabbitmq-retry	Your RabbitMQ retry queue
rabbitmq-success	Your RabbitMQ success queue
rabbitmq-verify	Should the server certificate be verified (only used for amqps:// connections)
received-log-format	Received log format
received-log-file	Received log filename
retry-interval	Interval for retrying to send
send-bin-log-file	Binary send log filename
send-log-file	Send log filename
send-log-format	Send log format
server-id	Server ID to prevent multiple instances from assigning same message ID
smarthost	Smarthost name (only needed if Smarthost is desired)
smarthost-password	Smarthost password
smarthost-port	Smarthost port
smarthost-username	Smarthost username
smtp-auth-results	Toggle adding authentication results to MIME header
smtp-certificate	Certificate for secure SMTP connections
smtp-check	Comma separated list of checks to perform on incoming messages
smtp-ciphers	Supported ciphers for secure SMTP connections
smtp-connections	Maximum amount of open TCP connections allowed
smtp-default-ips	List of default outgoing IP addresses
smtp-extract	Toggle automatic extraction of metadata
smtp-ip	SMTP server IP
smtp-key	Private key for secure SMTP connections
smtp-mappable-ips	List of mappable IP adresses
smtp-maxsize	Maximum message size to accept
smtp-password	Password for authenticating to SMTP server
smtp-port	Ports for incoming MailerQ connections
smtp-proxy	IPs to treat as connection from proxy server
smtp-range	Range of IP address to allow incoming email for
smtp-secure port	Ports for secure incoming MailerQ connections
smtp-sink-address	SMTP sink domain name or ip address
smtp-sink-password	SMTP sink password
smtp-sink-port	SMTP sink port
smtp-sink-username	SMTP sink username
smtp-threads	Number of threads started for SMTP traffic
smtp-unmappable-ips	List of unmappable IP addresses
smtp-username	Username for authenticating to SMTP server
spamassassin-host	Address for SpamAssassin daemon
spamassassin-port	Port for SpamAssassin daemon
spool-delay	Delay for processing spool directory files
spool-directory	Path to the directory to monitor
spool-extract	Toggle scanning for headers in spool directory mail
spool-fail-directory	Path to move files to that could not be picked up
spool-open-files	Amount of files that may be open simultaneously by the spool directory
spool-remove	Toggle removal of files from spool directory
spool-threads	Amount of threads to use for the spool directory
storage-address	Address for external message storage
storage-policy	Message store policy
storage-reschedule	Number of seconds to wait before a mail is retried
storage-threads	Storage threads
storage-timeout	Timeout for fetch operations
storage-ttl	Time to live: Storage reload interval
user	Change user for MTA
validate-envelope	Validate envelope address before sending
validate-recipient	Validate recipient address before sending
www-cache-control	Enable or disable browser cache
www-certificate	Certificate file for secure connection to management console
www-ciphers	Supported ciphers for secure management console
www-connections	Limit for simultaneous HTTP connections to built-in HTTP server
www-ip	Web interface IP (IP/port combination unique for every instance of MailerQ)
www-dir	Directory for installing MailerQ management console files
www-host	Web interface host (IP/port combination unique for every instance of MailerQ)
www-password	Management console password
www-port	Port number for the management console
www-private-key	Private key for secure connection to management console
www-secure-port	Secure (HTTPS) port number for the management console
www-url	The URL via which the management console is accessible

Setting	Description
daemon	Deamon process (deafault true)
disable-crash-report	Disable crash report
disable-crash-post	Disable automatic crash posting
extract-recipients	Read in a mime message from standard input and filter out the destination addresses
ignore-dot	Instruct MailerQ that dots do not have a special meaning
list-ips	List IP addresses
loopback	Loopback
notify-cluster	Notify cluster
paused	Pause
purge-database	Rebuilding the database tables
repair-database	Repair the database
version	Version

Code	Status (SMTP Error)	Description
211	2.1.1	System status, or system help reply
214	2.1.4	Help message
220	2.2.0	Service ready
221	2.2.1	Service closing transmission channel
250	2.5.0	Requested mail action okay, completed
251	2.5.1	User not local; will forward to <forward-path>
354	3.5.4	Start mail input; end with <CRLF>.<CRLF>
421	4.2.1	<domain> Service not available, closing transmission channel
450	4.5.0	Requested mail action not taken: mailbox unavailable
451	4.5.1	Requested action aborted: local error in processing
452	4.5.2	Requested action not taken: insufficient system storage
500	5.0.0	Syntax error, command unrecognised
501	5.0.1	Syntax error in parameters or arguments
502	5.0.2	Command not implemented
503	5.0.3	Bad sequence of commands
504	5.0.4	Command parameter not implemented
521	5.2.1	<domain> does not accept mail
530	5.3.0	Access denied
550	5.5.0	Requested action not taken: mailbox unavailable
551	5.5.1	User not local; please try <forward-path>
552	5.5.2	Requested mail action aborted: exceeded storage allocation
553	5.5.3	Requested action not taken: mailbox name not allowed
554	5.5.4	Transaction failed

x-mq-envelope	explicit envelope address
x-mq-ip	IP address to send mail from
x-mq-pool	pool identifier to send the message from
x-mq-tag	adds a tag to the message
x-mq-delayed	time when message should be sent
x-mq-maxdelivertime	max time for delivery
x-mq-maxattempts	max number of delivery attempts
x-mq-retries	interval in seconds between the attempts
x-mq-inlinecss	instruct MailerQ to inlinize the CSS code
x-mq-results-queue	alternative queue for the results
x-mq-failure-queue	alternative queue for the failures
x-mq-success-queue	alternative queue for the failures
x-mq-retry-queue	alternative queue for the retries
x-mq-smarthost-hostname	hostname of smarthost to send email to
x-mq-smarthost-port	portnumber of the smarthost
x-mq-smarthost-username	login for the smarthost
x-mq-smarthost-password	password to access the smarthost
x-mq-dsn-notify	the events for which to receive a DSN
x-mq-dsn-ret	whether to send the full body or just the headers in DSN
x-mq-dsn-orcpt	the original recipient for the DSN
x-mq-dsn-envid	unique identifier for the DSN message
x-mq-keepmime	do not remove the full mime object after delivery

Callable function	Description
MQ_email()	Access to the underlying email address
MQ_local()	Check whether a recipient address is "local"
MQ_setLocal()	Mark a recipient as "local"

state	state in the delivery where the error occured
result	type or result (accepted,timeout,lost,error,invalid)
time	time of the result
mta	name of the receiving mta (reported when the connection was set up)
from	ip from which the mail was sent
to	ip to which the mail was sent
authentication	if authentication/login was necessary for access, the authentication protocol used
cipher	the encryption protocol used (if the message was sent over a secure connection)
certificate	information about the ssl certificate that was issued by the receiving server
messages	number of messages sent over the same connection
code	SMTP result code
status	extended SMTP status code
description	answer received from receiving server
dsn	did the remote server implement the dsn protocol?

process	the input is checked and assigned to the from and to ip address between which it will be sent
storage	the mime data is loaded from external nosql storage
responsive	the json message is converted into a responsive email
personalize	the message is personalized if personalization data is available
dns	the hostname to which the mail should be sent is looked up in DNS
bind	a local IP address is chosen from which the mail is going to be sent
connect	a tcp connection is set up
intro	the TCP connection has been set up, waiting for initial welcome message from server
ehlo	the "EHLO" message has been sent
helo	the "HELO" message has been sent
starttls	the "STARTTLS" message has been sent
authplain	the "AUTH PLAIN" message has been sent
authlogin	the "AUTH LOGIN" message has been sent
authusername	the username for authentication has been sent
authpassword	the password for authentication has been sent
authcram	the "AUTH CRAM-MD5" message has been sent
authresponse	the response to the cram-md5 challenge has been sent
mailfrom	the "MAIL FROM" message has been sent
rcptto	the "RCPT TO" message has been sent
data	the "DATA" message has been sent
message	the full mime data followed by a dot has been sent
unknown	the connection is in an unknown state, for example when a pipeline failed

accepted	message was accepted (only reported in combination with state "message")
timeout	no answer was received in time
lost	connection was lost while waiting for an answer
invalid	an answer was received, but it could not be recognized as valid answer
error	an answer was received, but the answer contained a fatal error message

state	result
process	timeout	incoming message was expired (maxdelivertime or maxattempts exceeded)
process	error	the input json contains a mail that could not be assigned to an ip address (for example because no sufficient secure ip exists)
process	invalid	the input json contains a mail that could not be sent (for example due to license constraints, or because the recipient is missing or not parsable)
storage	lost	smtp connection was lost while loading data
storage	invalid	smtp response was received while loading data
storage	error	no data was found
responsive	error	responsiveemail.com algorithm could not turn json into mime
dns	error	dns lookup failure (domain does not exist / no ip addresses available for accepting mail)
bind	error	no local ip addresses available for sending mail

fatal	should be the message be retried, or was this result already a permanent failure
individual	override whether or not an error applies to a single message, or rather to any message sent to the domain
strange	is this is a strange type of result
greylisted	should this result be sent from the same ip later
fallback	should this result trigger a fallback server

Field	Required	Type	Description
pool	no	string	Pool that the pause applies to.
mta	no	string	MTA IP that the pause applies to.
domain	no	string	Domain that the pause applies to.
ip	no	string	Remote IP that the pause applies to.
tag	no	string	The tag that the pause applies to.
cluster	no	bool	Whether or not this pause is for the entire cluster or only this instance.

Modifier	description
base64_encode	base64 encoder
base64_decode	base64 decoder
cat:"string"	concatenates a string to variable
count	count number of elements in variable
count_characters	count number of characters in a string
count_paragraphs	count number of paragraphs in a text (by counting newlines)
count_words	count number of words in a text
default:default value	use default value if variable is not set
empty	check whether a variable is empty
escape:"string"	escape html characters (or other chars) inside a string
indent:num = 1:char = " "	put num whitespaces in front of every line
md5	perform md5 hashing
nl2br	replace newlines with html br tags
range:start = 0:end	truncate list to get the items between positions start and end
regex_replace:regex:replace_text	replace substrings using regular expression
replace:"string1":"string2"	replace occurrences of string1 with string2
sha1	perform sha1 hashing
sha256	perform sha256 hashing
sha512	sha512 hashing
spacify:separator = " "	place a separator between every input character
strlen	count the characters in a string
strstr:"substring":before = false	return the string starting from the first occurrence of substring if before = false. otherwise return the string until the first occurrence.
substr:start position:length	return the substring from start position onward, optionally truncated after length characters
tolower	convert all characters to lower case
toupper	convert all characters to upper case
trim	trim the white space and endline characters off both sides of the input
truncate:length = 80:etc = "...":break_words = false	truncate inputs that are longer than length and append etc at the end. break_words = true allows truncating parts of words
ucfirst	replace first character with an upper case character
urlencode	encode input for use in an url
urldecode	decode input for use in an url

envelope	envelope ("MAIL FROM") address
recipient	recipient ("RCPT TO") address
mime	full mime data to be sent
key	key to the mime data in external storage
keepmime	do not remove mime data after delivery
data	personalization data
ips	ip addresses to send the message from
pool	pool identifier to send the message from
nextattempt	properties for when the next attempt should be
maxdelivertime	time until which a delivery should be retried
maxattempts	max number of delivery attempts
retries	the delays between the delivery attempts
force	force delivery, even when errors occur or conversion is impossible
inlinecss	turn style blocks in html mails into inline style attributes
dkim	private keys to sign the mail
dsn	settings for delivery status notifications
queues	alternative rabbitmq queues for results
smarthost	smarthost settings
tags	the tags to add to the message
headers	add or change the mime headers
priority	the priority of the message

Function name	Description
mq_version()	Returns API version number to ensure that MailerQ and plugin are compatible
mq_initialize()	Called right after the plugin is activated, allows plugin to run initialization code
mq_cleanup()	Called right before MailerQ closes, allows plugin to run cleanup code

Function name	Description
mq_context_initialize()	Called after a worker thread is started, allows plugin to run thread specific initialization code
mq_context_cleanup()	Called right before a worker thread is stopped, allows plugin to run thread specific cleanup code

Ubuntu 14.04 and up	deb https://packages.copernica.com/debian stable main
Debian 8 and up	deb https://packages.copernica.com/debian stable main
Debian 6 and Debian 7	deb https://packages.copernica.com/debian legacy main

CentOS 7+, Red Hat 7+, Fedora 22+	https://packages.copernica.com/rpm/copernica.repo
CentOS 6, Red Hat 6, Fedora 21	https://packages.copernica.com/rpm-legacy/copernica.repo

Syntax	Meaning
`{$foo}`	Display a simple variable (no array or object).
`{$foo[4]}`	Display the 5th element of a zero-indexed array.
`{$foo.bar}`	Display the "bar" key value of an object.

Syntax	Meaning
`{$foo.bar.baz}`	Display the value behind the key "baz" inside the array "bar" which is a part of $foo.
`{$foo[4].baz}`	Display the value behind the key "baz" inside the 5th element of $foo.
`{$foo.bar.baz[4]}`	Display the 5th element of baz, which is in bar which is in $foo.

Function name	Description
mq_smtp_in_connect()	Called after an incoming TCP connection is established
mq_smtp_in_secure()	Called after an incoming TCP connection is turned into a secure connection
mq_smtp_in_authenticate()	Called after someone sends login credentials over an incoming SMTP connection
mq_smtp_in_mailfrom()	Called after the `MAIL FROM` instruction was received
mq_smtp_in_rcptto()	Called after the `RCPT TO` instruction was received
mq_smtp_in_data()	Called after MIME data was received over the incoming connection
mq_smtp_in_message()	Called after the entire message was received and is turned into a JSON message
mq_smtp_in_close()	Called after an incoming SMTP connection is closed

Function name	Description
mq_smtp_out_data()	Called by MailerQ when the connection enters data state
mq_smtp_out_sent()	Called by MailerQ after all mime data has been sent

hostname	server name that received the message
received	time when the mail was received
message-id	unique message id generated for the mail (only used when received via smtp)
connection	connection info (only used when received via smtp)
spool	spool info (only used when received from spool dir)
cli	command info (only used when received from cli)
checks	array with the results of the SPF, DKIM and DMARC checks

Field	Required	Type	Description
code	yes	int	Numeric error code between 200 and 599 (smtp error codes).
extended	false	string	Extended SMTP error code, e.g. 5.7.1.
description	false	string	Description to put in the message result.
pool	no	string	Pool that the error applies to.
mta	no	string	MTA IP that the error applies to.
domain	no	string	Domain that the error applies to.
tag	no	string	The tag that the error applies to.
cluster	no	bool	Whether or not this error is for the entire cluster or only this instance.

Function name	Description
mq_smtp_in_message()	Called by MailerQ when a message is received on an incoming SMTP connection
mq_smtp_out_data()	Called by MailerQ right after it has sent the "DATA" command and is about the send MIME data

Function name	Description
MQ_envelope()	Get access to the envelope address
MQ_setEnvelope()	Set the envelope address
MQ_recipient()	Get access to the recipient address
MQ_setRecipient()	Set the recipient address
MQ_mime()	Get access to the MIME data
MQ_setMime()	Get the MIME data

Syntax example	Meaning
$a == $b	$a and $b are equal
$a != $b	$a and $b are not equal
$a > $b	$a is greater than $b
$a >= $b	$a is greater than or equal to $b
$a < $b	$a is less than $b
$a <= $b	$a is less than or equal to $b
$a =~ "regex"	$a matches with supplied regular expression
$a AND $b	$a and $b are true
$a OR $b	$a or $b (or both) are true
not $a	Negation, will invert the boolean value of $a

Function name	Description
MQ_continue()	Tell MailerQ to call the next plugin
MQ_complete()	Tell MailerQ to skip all further plugins
MQ_retry()	Tell MailerQ to restart calling all plugins

Tables	Description
libopenssl	Used for TLS encryption, license checking and base64 encoding
libz	Used for compression algorithms
libmagic	Used to detect the mime-type of files
libuuid1	Used for generating globally unique identifiers
libidn	Used for parsing international domain names
libxml2	Used for parsing and modifying XML/HTML code
libimagemagick	Used to find out the dimensions of images
libmysqlclient	Used to connect to a mysql/mariadb database
libmariadbclient	Used to connect to a mysql/mariadb database
libpq	Used to to connect to a Postgresql database
libsqlite3	Used to process sqlite3 database files
libmongo-c-driver	Used to connect to a MongoDB NoSQL server
libcouchbase	Used to connect to a Couchbase server

notify	comma separated events that trigger a notification (FAILURE, DELAY, SUCCESS, NEVER)
ret	should the notification hold the full original mail or just the headers (FULL, HDRS)
orcpt	the address to be included in the notification as "original-recipient"
envid	unique identifier to be included in the notification as "original-envelope-id"

Configuration file

Are you looking for more settings?

More information

Configuration A-Z

Boolean options

Rest API v1

Function MQ_mime

Function MQ_connectionData

Function MQ_setLocal

Function MQ_setMime

SMTP reply codes

Mail Transfer Agent Management Console

Setting up the Management Console

Setting up a secure management console

Announcing the interface on the cluster

Rendering emails

Advanced caching options

MailerQ Transport Plugin for Swift Mailer

example.php

Special MIME headers

Example message

Envelope address

Local IP addresses

Tags

Delivery time

Maximum number of attempts

Interval between attempts

Inlinize CSS

Custom result queues

Smarthost settings

DSN settings

Keep messages after delivery

Function MQ_ioUnwatch

Function MQ_continue

Function MQ_retry

Function MQ_setConnectionData

MailerQ Frequently Asked Questions

Technical Questions

Does MailerQ support IPv6?

Can I see my opens, clicks, etc. in MailerQ?

What happens when an email cannot be delivered?

License related Questions

Where can I find a MailerQ license?

How do I renew a license?

What if I accidentally delete my license?

Are there any extra costs?

Function MQ_fileDescriptor

Callback mq_cleanup()

Function mq_smtp_in_secure

MailerQ plugin development

How are plugins loaded?

Performance and event loops

A minimalistic plugin

A real world example

Do you find the API too limited?

Structure MQ_Address

Available functions

Function MQ_authenticated

How to send email with MailerQ?

Function mq_smtp_in_rcptto

Result message queues

Different result queues

Example scenario

Understanding the results

Added properties

Delivery states

Result types

Special combinations

Secure connections

Overriding errors

Function mq_context_initialize

Function mq_smtp_in_connect

Function MQ_json

Spool directory

Config file options

Function mq_context_cleanup

Command Line utility

End of message

Envelope address

Sending emails from file

`example.php`

Callable function	Description
MQ_fileDescriptor()	Retrieve the filedescriptor linked to a connection
MQ_send()	Send data over a SMTP connection
MQ_authenticated()	Returns whether this is an authenticated connection
MQ_setAuthenticated()	Mark a connection as an authenticated connection
MQ_secure()	Returns whether this is a secure TLS connection
MQ_connectionData()	Retrieve the data that is associated with the SMTP connection
MQ_setConnectionData()	Associated data with the SMTP connection

Tables	Description
capacity	all delivery capacities, eg max number of connections
capacity_rules	capacity rules per domain / MTA IP
dkim_keys	DKIM keys to sign outgoing mails
dkim_patterns	rules that decide what DKIM keys to use
dns	overridden dns lookups
errors	Forced errors
flood_responses	alternative delivery limits to use when certain responses come in
ips	all MailerQ's IP addresses
locals	local email addresses
mtanames	alternative "EHLO" names
paused	deliveries on pause
response_actions	response action, eg send mail from a different IP
response_patterns	patterns of responses that has to match
response_patterns_actions	what kind of response actions must be executed
rewrite_actions	actions to perform when a message is loaded eg send from a different IP
rewrite_triggers	triggers to fire rewrite actions

Implementable function	Description
mq_context_initialize()	Called by MailerQ when a worker thread is created
mq_context_cleanup()	Called by MailerQ when a worker thread is destroyed

Callable function	Description
MQ_contextData()	Retrieve the plugin managed data from the context
MQ_setContextData()	Assign plugin managed data to the context

Callable function	Description
MQ_ev()	Access to the underlying libev instance
MQ_ioWatch()	Watch a filedescriptor for activity
MQ_ioUnwatch()	Stop watching a filedescriptor for activity
MQ_startTimer()	Start a timer
MQ_stopTimer()	Stop a timer
MQ_resetTimer()	Reset a timer to a new timeout