Exportable functions
After your plugin is loaded, MailerQ starts making calls to it. To do this, MailerQ simply tries to locate specific functions in the plugin shared object file, and if it finds one or more of these functions, it will make calls to them every time a certain event occurs. There is one function that is required, mq_version(), but all others are optional. You only have to implement the optional functions if you want your plugin to override the default MailerQ behavior.
| 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 |
Before we continue, a single paragraph about the function naming convention of the MailerQ API. There are two type of functions: The first type of functions are the functions that your plugin can implement, and that are called by MailerQ when certain events occur -- these are functions like the ones listed in the table above. For these type of functions we use all lowercase characters. The other type of functions are functions that are offered by the MailerQ API, and that can be called by your plugin. These functions all have the uppercase "MQ_" prefix, and use CamelCase notation. The declarations of this second group of functions can be found in the "mailerq.h" header file.
Multi-threading functions
MailerQ is a multi-threading application, with multiple worker threads that are all busy sending and receiving emails. If you write a plugin, it is important to realize this, because you cannot always safely access the same global data from your plugin functions. Locking might be necessary if you access global data from these multiple threads, and it could be useful to use per-thread data.
For every worker thread, MailerQ creates a MQ_Context structure that is passed to most of the plugin callback functions. For every worker thread that is created, and for every worker thread that is stopped, MailerQ calls the mq_context_initialize() and mq_context_cleanup() functions (but of course only if these functions exist in your plugin). You can implement these functions to run your own per-thread initialization or 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 |
Plugins for incoming emails
If you want your plugin to interact with incoming SMTP traffic, you can implement one or more of the functions from the following table. When MailerQ loads your plugin, it tries to locate any of the following functions, and when it can find one or more of these functions, it will make calls to them every time the relevant event occurs. All functions are optional, you only have to write the ones that you need.
| 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 |
Plugins for outgoing emails
If you want your plugin to interact with outgoing SMTP traffic, you can add one or more of the functions from the following table to your plugin. MailerQ will call them every time a message is being sent.
| 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 |
