Introduction

About MailBee.NET Queue

MailBee.NET Queue is a background Windows service which allows you to improve performance and responsiveness of your applications which send large volumes of e-mails. Shipped with the source code making it possible to fine-tune it for your needs.

When needed

Usually, in order to send an e-mail, the application needs to make a connection to the mail server and then submit the e-mail to this server using SMTP protocol. This may take significant time. Also, many mail servers limit the maximum number of e-mails which can be accepted from a single IP address per second, hour and so on. If you have a large number of e-mails to be sent, you need to distribute the load over time in order to not violate the restrictions implied by the server.

For instance, if the server allows you to submit only 100 e-mails per hour and you have 1000 e-mails waiting, you cannot send them faster than in 10 hours.

With MailBee.NET Queue, your application can quickly write all the outgoing e-mails as .EML files in MailBee.NET Queue pickup folder, and proceed to other tasks or simply exit if it has no more work to do ("fire and forget" approach).

MailBee.NET Queue service which operates in the background monitors this folder and sends all the e-mails which appear there as .EML files. The entire process is not limited in time so that you can deliver very large volumes of e-mails even if your mail server is slow or too restrictive in terms of the allowed throughput.

You can also examine MailBee.NET Queue source code as a real-world example of using MailBee.NET Objects.

How to send e-mails to MailBee.NET Queue

You can use virtually any tool capable of producing MIME .EML files in order to feed MailBee.NET Queue. For instance, MailBee.NET Objects and MailBee Objects components provide extra methods to submit e-mails to MailBee.NET Queue rather than to an SMTP server (see Submitting e-mails to MailBee.NET Queue topic for details). You can even create .EML files manually or with your own scripts because MIME format is very simple if your e-mails are also simple (no attachments, just text).

Getting Started

Once installed, MailBee.NET Queue requires just a few things to be configured. First of all, you need a trial or permanent license key. MailBee.NET Queue uses MailBee.NET SMTP component for its work. In fact, the required license key is MailBee.NET SMTP license key. If you already have a license key for MailBee.NET SMTP component or for the entire MailBee.NET Objects bundle, you do not need any additional key for MailBee.NET Queue.

If you don't have a key, you can get a trial key during downloading MailBee.NET Queue. Or you can use "Get a Trial Key" tool in MailBee.NET Queue Start Menu. The second method may, however, not always work due to permission issues or (see Troubleshooting for details).

Also, MailBee.NET Queue needs to know which folder on the filesystem it will monitor and use as input (the pickup folder). Your applications will write .EML files to that folder.

Finally, you need to tell MailBee.NET Queue which SMTP relay server to use (and, optionally, SMTP username/password because most mail servers do not allow unauthenticated users to relay mail to external domains).

You can also enable logging all the activities into a log file - this can be of much help when troubleshooting.

How to configure

You can directly edit the XML config file (more flexible, more features available) or use MailBee.NET Queue Control Panel application (only basic features are supported but easy to use). You can combine both methods together because the Control Panel app does nothing but reads and writes the config file. For instance, use Control Panel app for basic configuration and edit the config file if you need to fine-tune something.

How to setup multiple configuration sets

If you need to have more than one active configuration (for instance, high-priority queue for urgent e-mails and low-priority queue for the rest), you can set up multiple MailBee.NET Queue services.

How to run

Once configured, you can start using MailBee.NET Queue. To start or stop the service, you can use MailBee.NET Queue Control Panel application, click Start/Stop/Restart buttons in MailBee.NET Queue Start Menu, run .bat files in the folder where you installed MailBee.NET Queue, or use Services tool in Windows.

How to extend

MailBee.NET Queue ships with the source code (Visual Studio 2008 project, can be opened in modern Visual Studio versions as well). You can extend or modify it in any way to get even more advanced or specific functionality. For instance, you can setup delivery notification e-mails (DSNs), use events of underlying Smtp object to track progress of all operations, and much more.

You are allowed to redistribute the modified versions of MailBee.NET Queue, including rebranding. The only requirement: the license key must not be visible to end users or any other 3rd parties. To achieve this, you can hard-code the key in the application if you don't ship the source code, or save the key in the registry if you do.

Send feedback to AfterLogic

Copyright © 2011-2019 AfterLogic Corporation. All rights reserved.


Sales, Licensing, and Support

Sales

Licenses can be purchased online at https://afterlogic.com/purchase/net-smtp-component.

To purchase via a reseller, proceed at https://afterlogic.com/resellers.

Note that if you already have MailBee.NET SMTP or MailBee.NET Objects license key, you can use it with MailBee.NET Queue. No separate key required.

How to obtain support

AfterLogic provides free technical support for MailBee products before and after the sale:

  • Request Support via online form
  • You are welcome to visit our Online Support Forum
  • Or e-mail your inquires to support@afterlogic.com


Using MailBee.NET Queue Control Panel

Basic functions

You can use MailBee.NET Queue Control Panel to set up and start Windows service of MailBee.NET Queue, stop and remove this service from the services list, and perform some basic configuration and maintenance of MailBee.NET Queue. This includes setting the license key, setting the folders which will be used as the .EML files pickup folder and the folder for bad e-mails which could not be sent, SMTP relay server configuration, accessing log files.

To start MailBee.NET Queue Control Panel, click .NET Queue Control Panel link in MailBee.NET Queue Start Menu application.

Main Tab

License Key - enter a valid trial or permanent MailBee.NET Queue key here. MailBee.NET Queue simply passes this key to MailBee.NET SMTP component which is being used internally for all mail operations. Thus, any valid key for MailBee.NET SMTP component will work as MailBee.NET Queue key. If you have a unified key for the entire MailBee.NET Objects bundle, it will work as well.

Queue Root - a folder on the local filesystem where MailBee.NET Queue will store its data folders. These folders include the pickup folder and the bad folder. Log files folder also resides in the Queue Root.

Pickup Folder - you cannot set it manually, it's always the "Pickup" sub-folder of the Queue Root folder. This is the folder where your applications will write .EML files representing e-mails pending for delivery.

Bad Folder - you cannot set it manually, it's always the "Bad" sub-folder of the Queue Root folder. This is the folder where MailBee.NET Queue moves the e-mails which could not be sent.

Max Threads - if 1, MailBee.NET Queue will use only a single thread to make connections in order to deliver e-mails through SMTP connections. Using multiple threads (up to 60 supported) may greatly improve the overall performance.

Test button - allows you to quickly check if the license key you entered is correct.

Browse button - allows you to select another Queue Root folder.

Retry Bads button - moves all .EML files from Bad folder back to Pickup folder.

Start and Stop buttons - install/start and stop/remove MailBee.NET Queue Windows service. You can also use links in MailBee.NET Queue folder of Start/Programs menu.

Save Settings button - saves all the settings (from Main and other tabs) to the XML app.config file which resides in the folder where MailBee.NET Queue is installed (e.g. C:\MailBeeNetQueue\app.config). You can also edit this file manually to fine-tune the configuration.

SMTP Tab

Server Name - MailBee.NET Queue will use this SMTP relay server to deliver e-mails. In case if you want to deliver e-mails via multiple SMTP relay servers, via DNS MX lookup or use backup servers you need to edit app.config file manually.

Port - usually, 25. For SSL-only mail services like Gmail, the port is usually 465.

SSL Mode - depends on SSL settings of your mail server. If no SSL, port 25 or 587 is usually used. For SSL-only case, port 465 is the most common setting. For STARTTLS modes when the connection starts in non-SSL mode and then switches in SSL with STARTTLS command, ports 25 or 587 are used most often.

Authentication - most mail servers require clients to authenticate themselves in order to permit relaying e-mails to external domains. Specify your SMTP login and password if your server does not relay from anonymous users.

Max Simultaneous Connections - how many connections (max.) MailBee.NET Queue can make to the given SMTP server simultaneously. Many servers allow only a few simultaneous connections from a single IP address. Makes sense only if Max Threads on Main tab is not 1.

Max E-mails per Session - how many e-mails (max.) MailBee.NET Queue can send through a single SMTP session. Many servers limit this value (or they can limit the total number of recipients of all e-mails sent through a single SMTP session).

Pause Between Sessions - the amount of time (in milliseconds) to wait between two successive SMTP sessions. Many servers do not allow making connections too often. You also combine this with Max E-mails per Session parameter to adjust the overall throughput of MailBee.NET Queue. For instance, if Pause Between Sessions is 500 (or 0.5 sec) and Max E-mails per Session is 3, MailBee.NET Queue will send up to 6 e-mails per second (up to 3 e-mails every 0.5 sec).

Disable CHUNKING - The ESMTP extension called CHUNKING can increase sending performance but sometimes it causes problems (for instance, MS Exchange server with Tar Pitting enabled significantly delays its SMTP responses if the client is using CHUNKING). This is because CHUNKING is often used by spammers to increase throughput of their e-mail clients while most legitimate e-mail clients like Outlook still don't use it.

Logging Tab

Log Filename - the path to the file where MailBee.NET Queue will log all its activities. The path may include {...} block which is treated in a special way. For instance, {yyyy-MM-dd-HH-mm} will result in changing the log filename every minute. This allows for splitting the log into multiple files. Note: the log filename does not actually change until the current portion of the e-mails which are being sent right now is finished.

You can also view, clear, enable or disable logging here. Note that using logging slightly degrades performance and consumes disk space (MailBee.NET Queue produces very detailed logs, 1-2KB per e-mail sent).


Using app.config to configure MailBee.NET Queue

Getting started

When you configure MailBee.NET Queue with its Control Panel application, it actually stores all the settings in app.config file. You can also manually edit this file in case if you need advanced features not available through the Control Panel application. Also, you can create app.config file programmatically.

You can use Control Panel application and manual editing all together. For instance, if you manually added some settings which are not supported by Control Panel application, then opened that application, changed other options and saved the settings, your custom changes will not be lost. In other words, Control Panel application will preserve any custom changes you made.

app.config is the standard XML configuration file of a .NET application. All the configuration is stored within <Configuration> section. When MailBee.NET Queue Control Panel writes into this file, it simply serializes Config object of MailBee.NET Queue API (MailBeeNetQueueCore.dll). The same way, when MailBee.NET Queue itself or its Control Panel reads this file, it actually deserializes that Config object. Config class provides Load and Save methods which can be used to read or write app.config file.

To edit app.config manually, click Edit Config File button in "MailBee.NET Queue Start Menu" tool.

Advanced features which you can configure with app.config

  • You can tell the service to keep x-sender and x-receiver headers which are added by MailBee.NET Objects and MailBee Objects to specify actual sender and recipients of the message (as they can be different from From/To/CC/BCC). Usually, these service headers are not needed in the actual messages being sent and thus get removed during sending. But if you want to keep them for some reason, you can set <KeepXSenderXReceiver>true</KeepXSenderXReceiver> (the default is false). Note that true/false is case-sensitive in XML (True/False won't work).
  • By default, MailBee.NET Queue doesn't add/replace Date header with current date when loading and sending out source .EML files. If you want to make sure Date is set to the actual moment of sending, set <SetDateOnSend>true</SetDateOnSend>. This can be useful in case if your e-mails get rejected by spam filters of your recipients (they don't like when the date in Date header and the actual date of receiving the message by the recipient's server don't match).
  • You can define multiple <SmtpServer> entries in <SmtpServers> section. The Control Panel allows you to specify only a single SMTP relay server but MailBee.NET Queue is capable of using server farms for sending very large volumes of e-mails, fail-over servers, etc.
  • Edit any properties in <SmtpServer> section. The Control Panel allows you to edit most but not all properties of SMTP server. Some settings like proxy server configuration, allowance of failed recipients and many others can only be edited via app.config file.
  • Enable "direct send" mode without any SMTP relay server by adding <DnsServer> entries to <DnsServers> collection. This can be used to send directly to recipients' MX servers via DNS MX lookup. You can still use a relay server and thus "direct send" will play the role of "fail-over" server. To use "direct send" on its own, you must remove all entries from <SmtpServers> section.

<SmtpServers> and <DnsServers> sections must reside within <Queue> section which is in turn nested into <Configuration> section.

Below is the example of adding a DNS server for "direct send" mode. If you remove <SmtpServers> section, only "direct send" mode will be used. If you leave <SmtpServers> as-is, "direct send" will be used only as a fail-over for SMTP relay. To reverse things ("direct send" is primary, SMTP relay is fail-over), adjust their Priority values (less value means higher priority). You can add <DnsServers>...</DnsServers> just below </SmtpServers> or remove the entire <SmtpServers>...</SmtpServers> at all if you want to use "direct send" only. You can add more than one DNS server if you need to.

<DnsServers>
  <DnsServer>
    <Host>192.168.0.1</Host>
    <Priority>1</Priority>
    <UdpRetryCount>2</UdpRetryCount>
    <UdpTimeout>5000</UdpTimeout>
  </DnsServer>
 </DnsServers>

Using Config object in your applications

First, add a reference to MailBeeNetQueueCore.dll and MailBee.NET.dll to your application. You can find both .DLLs in the folder where you installed MailBee.NET Queue.

Declare namespaces of MailBee.NET Objects and MailBee.NET Queue in your code with using directive in C# and Imports in Visual Basic.

To read MailBee.NET Queue configuration from a file, use the static method Load of MailBee.Queue.Config class. This method returns the Config object containing the configuration. To save changes, use Save method of the Config object.

You can find the detailed VB and C# examples of using Config object to configure MailBee.NET Queue in MailBeeNetQueue/Source/Samples/VB EditConfig (and C# EditConfig, respectively) folder of My Documents (you can also use "Browse Samples" button in "MailBee.NET Queue Start Menu" tool to find Samples folder). EditConfig sample consists of several code snippets. Some of them configure the things which are not available in the Control Panel application (such as "direct send" mode).


Troubleshooting

MailBee.NET Queue

Running multiple queues

When needed

If you have different sorts of e-mails, you may need to use different settings for each group of them. MailBee.NET Queue lets you run multiple services, each with its own name. You'll need to copy MailBee.NET Queue in a separate location to get a new instance. Each instance will have its own set including the service app itself, the control panel app, app.config, etc. Working folders in app.config must be separate for each instance too (it's technically possible to have two instances "see" the same working folder location but it won't work reliably and hardly has any practical meaning).

"servicename" file

The default Windows service name is MailBee.NET Queue. If you need multiple queues, a unique name must be set for every instance of MailBee.NET Queue. For that, put a file named servicename in the root folder of every instance of MailBee.NET Queue (the folder where MailBeeNetQueue.exe resides). The contents of the file must be the queue name. For instance, if you have two queues, you can put Service1 and Service2 in them, respectively. Note that servicename files must have no extension in their filenames (e.g. Service1.txt won't work).


Submitting e-mails to MailBee.NET Queue

Basics

MailBee.NET Queue consumes e-mails to be sent as .EML files. The .EML extension denotes files in MIME format. This format is widely supported by most e-mail systems so you can use not only MailBee.NET Objects and MailBee Objects but virtually any MIME-capable software to feed MailBee.NET Queue.

MailBee.NET Queue also supports special MIME headers x-sender and x-receiver. They allow you to override From and To/CC/BCC values in the e-mail. Example of the message header section containing such headers (produced with MailBee.NET Objects):

x-sender: returnpath@domain.com
x-receiver: george@competing-company-2.com
x-receiver: alice.smith@competing-company-1.com
MIME-Version: 1.0
X-Mailer: MailBee.NET 9.0.2.472
From: "John Doe"
To: undisclosed recipients
Subject: Test e-mail 2
Date: Fri, 30 Jan 2015 14:02:40 -0500
Message-ID: <1.7d974c67506d1a456cf8@server>
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html

Using MailBee.NET Objects to submit e-mails

Besides the source code of MailBee.NET Queue itself, there are some VB and C# sample projects including sending a single e-mail in a number of ways and mail merge over database. You can find them in MailBeeNetQueue/Source/Samples folder of "My Documents" (or just click "Browse Samples" buttons in "MailBee.NET Queue Start Menu").

For mail merge samples, be sure you have the proper MS Access driver (the samples contain the details on that). Using MS Access is not a requirement, MailBee.NET Objects can do mail merge over any data source, it's just how that samples are implemented to be self-contained and independent from external data sources like SQL Server.

Another source of examples is the code snippets which appear in MailBee.NET Objects Documentation on Smtp.SubmitToPickupFolder and Smtp.SubmitJobsToPickupFolder methods, and in MailBee.NET Objects Developer's Guide: Submit to MailBee.NET Queue for increased or limited throughput.

The main idea is that you compose an e-mail and then call a method like Smtp.SubmitJobsToPickupFolder to write .EML file to the folder from where MailBee.NET Queue can then pick up the file, read the contained e-mail and send it out. The pickup folder location depends on MailBee.NET Queue configuration (you can easily change it) and by default is "C:\MailBeeNetQueue Files\Pickup".


Compiling MailBee.NET Queue from sources

Source code project

MailBee.NET Queue ships with the source code which is implemented as Visual Studio 2008 C# solution. It includes 3 projects: API, Windows service, control panel application. Also, a number of C# and VB samples which highlight usage of MailBee.NET Queue are shipped with the product. They are Visual Studio 2008 projects too. All of the above can be successfully opened in newer versions of Visual Studio as well.

Typical problems

  • You get issues with MailBee.NET Queue Windows service and it's hard to debug a Windows service. In this case, open MailBee.NET Queue/MessageQueue.cs, find the ending of Main method, and follow the code comments to convert Windows service into a normal console application which you can easily run and debug.
  • Not exactly a problem with MailBee.NET Queue itself but there may be an issue with running mail merge samples (in Samples folder). They are using MS Access database which (JET driver) which may not be present in your system. Follow instructions in the source code of these samples on how to overcome this.


Troubleshooting

Use logging

MailBee.NET Queue can log all the activities in log files. These logs are very detailed and can help you discover why the issue you're experiencing occurs.

Control Panel of MailBee.NET Queue provides all the controls needed for enabling, clearing or viewing the log.

Check sending e-mail using another SMTP client

If e-mails are not being sent, make sure you can send them using another e-mail client like Mozilla Thunderbird. It's important for that mail client to be installed on the same machine as MailBee.NET Queue and to use exactly the same SMTP settings. Do not use MS Office Outlook because it's usually configured to send e-mails via MAPI rather than SMTP.

Sometimes, however, the fact that you can send with Outlook Express does not prove there is a problem in MailBee.NET Queue since many firewalls may allow outbound connections for well-known applications like Outlook Express but block connections made by other applications (like MailBee.NET Queue).

Typical problems and solutions

  • E-mails cannot be sent to external domains. Enable SMTP authentication in MailBee.NET Queue.
  • Connection with the SMTP server cannot be established on port 25. The server may be SSL-only (port 465), listen to port 587 instead of 25, or port 25 is simply blocked by firewall.
  • Connection with the SMTP server cannot be established on port 465. The server is SSL-only while MailBee.NET Queue tries to connect to this port as if it were a regular non-SSL port. Set the appropriate SSL mode on SMTP tab of MailBee.NET Queue Control Panel.
  • Some e-mails could not be sent but they can be sent a bit later (if retried). You've probably reached the allowed throughput limits of your server (for instance, tried to send more than 5 e-mails per session if this server allows no more than 5 e-mails per session). In MailBee.NET Queue Control Panel, adjust the appropriate parameters (like Max E-mails per Session) accordingly the limits imposed by your server. You can read more on these parameters in Using MailBee.NET Queue Control Panel (SMTP Tab) or in MailBee.NET Objects documentation (MaxConnectionCount, MaxSendPerSessionCount and PauseInterval properties of SmtpServer object).
  • E-mail delivery issues (i.e. e-mails are being sent successfully but still not received by end recipients). Usually, this means your e-mails end up in Spam folder of end users' mailboxes. Make sure your SMTP relay has all the DNS records assigned including valid MX, PTR, SPF entries. Sign your e-mails with DKIM or DomainKeys signatures (MailBee.NET Objects supports both). Try to change the IP address of the sending server (your IP address could get blacklisted).
  • E-mail submission to the server interrupts in the middle or takes minutes to complete. This most often occurs with MS Exchange servers which support CHUNKING extension for better performance but in fact work slower or do not work at all when CHUNKING is being used. Disable chunking on SMTP Tab of MailBee.NET Queue Control Panel.
  • The license key stored in the registry (for instance, the key generated by "Get a Trial Key" tool) does not work while the same key stored in app.config or MailBee.NET Queue Control Panel works. This is either permission-related issue (the application can't read certain branch of the registry) or virtual registry conflict. Vista and newer OSes can use different registries for different types of applications (or even for the same application which is being run in different contexts - with admin privileges or normally). This results in "not seeing" by MailBee.NET Queue the license key written by another application in the registry branch with the same name (because they are in fact different branches). If you can't overcome registry issues, you can save the key in app.config unless you need to hide the key to prevent its unauthorized distribution. If you need to hide the key, you can hard-code it in the MailBee.NET Queue code (you can do this because MailBee.NET Queue ships with the source code).


Version History

  • 1.6.2

    • MailBee.NET Queue now attempts to use TLS 1.2 as SSL protocol (when available) and falls back to TLS 1.0 only if TLS 1.2 and TLS 1.1 is not supported by the SMTP server.
    • MailBee.NET.dll update to v12.0 (fixes misc. issues), requires license key in MN120 format.
    • Documentation improvements.

  • 1.6.1

    • MailBee.NET Queue sources (shipped with the product) now contain code how to prevent MailBee from automatic adding Message-ID to the messages being sent out.
    • MailBee.NET.dll update to v11.2. This provides: SIZE argument of MAIL FROM command, short path of SMTP authentication (required by Microsoft SMTP servers), no extra CRLF in the end of DATA transmission in SMTP.

  • 1.6

    • MailBee.NET Queue no longer automatically adds plain-text version of HTML body to HTML-only messages.
    • sha256 signatures and strong names in addition to sha1 signatures for .NET Queue .DLL and .EXE files.
    • MailBee.NET.dll mail engine is now v11.0 (fixes misc. issues), requires license key in MN110 format.

  • 1.5.1

    • MailBee.NET Queue now preserves Date header in e-mails (can be reverted with setting SetDateOnSend to true in the config file).
    • MailBee.NET.dll update to the latest build.

  • 1.5

    • MailBee.NET.dll mail engine is now v10.0 (fixes misc. issues).
    • Multiple simultaneoulsy running MailBee.NET Queue services with different configuration (servicename file).

  • 1.4

    • MailBee.NET.dll mail engine is now v9.0 (fixes misc. issues).
    • Authenticode digital signatures for all .DLLs, executables and installer.
    • Documentation's new look.

  • 1.3.2

    • Integrated Windows Authentication improvements. Works much better with MS Exchange and IIS SMTP service now.

  • 1.3.1

    • New KeepXSenderXReceiver parameter in app.config. The default is false which means "when sending, delete x-sender and x-receiver from e-mails".

  • 1.3

    • New Windows 8/8.1 compatible Start Menu application.
    • Improved support of 64-bit systems.
    • Can work on systems without .NET 2.0/3.5 installed (e.g. Windows 8.1).
    • Better UAC compatibility.
    • Mail merge samples updated to use a newer OLEDB MS Access driver.
    • Documentation revised.
    • MailBee.NET.dll mail engine is now v8.0 (fixes misc. issues).

  • 1.2

    • Bugfixes.
    • Documentation revised.
    • MailBee.NET.dll mail engine updated to the latest version (fixes misc. issues).

  • 1.1

    • VB samples added.
    • C# samples revised.
    • Documentation revised.
    • MailBee.NET.dll mail engine updated to the latest version (fixes misc. issues).

  • 1.0

    • Initial version.