OSP Mail Delivery Service

Introduction

With the Poco::OSP::Mail::MailDeliveryService, the Open Service Platform provides a standard way of sending email messages from an OSP-based application. While it's possible for any OSP-based application to use Poco::Net::SMTPClientSession directly to send email messages, using the MailDeliveryService has a few advantages:

Centralized configuration: the MailDeliveryService is configured using the global application configuration. Thus there is no need to configure individual SMTPClientSession instances with parameters like SMTP host and port, authentication, etc.
Queued delivery: The MailDeliveryService internally uses a queue to serialize delivery of mail messages to the outgoing SMTP server. This reduces server load by preventing multiple SMTP connections from the same application if multiple threads (e.g. HTTP request handlers) are sending out messages. Furthermore, there is no need to wait for the delivery of the message, as the queue is processed in the background.

Using the MailDeliveryService

The MailDeliveryService is provided by the com.appinf.osp.mail bundle and registered under the service name "com.appinf.osp.mail".

To send a mail message, obtain an instance of the service, create a Poco::Net::MailMessage object, and call the sendMessage() member function. This will return an instance of Poco::OSP::Mail::MailDeliveryHandle which can be used to track the progress of the message on its way to the outgoing SMTP server, if required. For that purpose, the MailDeliveryHandle class provides various events, as well as waiting functions. If not information about the delivery of the message is needed, the object can also be discarded.

Following is an example for sending an email message:

// obtain MailDeliveryService instance
Poco::OSP::Mail::MailDeliveryService::Ptr pMailDeliveryService =
    Poco::OSP::ServiceFinder::find<Poco::OSP::Mail::MailDeliveryService>(c());

if (pMailDeliveryService)
{
    // compose mail message and send it
    Poco::OSP::Mail::MailMessagePtr pMsg = new Poco::Net::MailMessage;
    pMsg->setContentType("text/plain; charset=UTF-8");
    pMsg->addRecipient(Poco::Net::MailRecipient(Poco::Net::MailRecipient::PRIMARY_RECIPIENT, "mail@company.com"));
    pMsg->setSubject("Hello from OSP!");
    pMsg->setContent("This message was sent using the OSP MailDeliveryService.\n");
    pMailDeliveryService->sendMessage(pMsg); // ignore returned MailDeliveryHandle
}
else
{
    // service not available
}

Mail messages can also contain attachments, etc. For details please refer to the Poco::Net::MailMessage class. When sending attachments, make sure that the resource containing the attachment (e.g., a temporary file) remains available until the mail message has been delivered to the outgoing SMTP server. Remember that mail messages are delivered asynchronously, and very probably have not been sent when the Poco::OSP::Mail::MailDeliveryService::sendMessage() member function returns. You can use the returned Poco::OSP::Mail::MailDeliveryHandle object to track progress.

Note that the mail message queue is kept in main memory, so any messages remaining in the queue when the application terminates will not be delivered.

The size of the queue can be limited by a configuration setting. The default limit is 100 messages. The Poco::OSP::Mail::MailDeliveryService::sendMessage() function will throw a Poco::RuntimeException if this limit is exceeded.