Introduction

Sending mails is quite simple. But there are requirements to provide multiple implementations. Some customers want to:

Send mails immediately
Store failed mails in the database
Resend failed mails
Send mails asynchronously with another application
Store all mails in the database without sending
Store all mails in the database and take a protocol about sending
A different organization should use a different mail server for sending (hosting environments)

Two cartridges are involved:

bc_mail	for service-independent artifacts
ac_mail	for service implementations

Reference

Please also have a look at the corresponding cookbook .

Service-Independent Artifacts

Service-independent artifacts are:

Interfaces defining an email as data object: Mail, MailAttachment, MailReceiver
Pipelets to create and send an email
Service interface SendMailService

Implementation

The business logic triggers sending a mail. The code must collect data for receivers, attachments. The MailMgr provides methods to create such new data objects. The implementation of that manager interface creates transient data objects. These objects can be stored later by service implementations.

Pipelets

Name	Cartridge	Description
SendMail	core	This pipelet does not use mail services at all; it is useful for administrator mails. It was available before Enfinity 6.4.
ProcessMail	bc_mail	This pipelet has the same parameter as SendMail of core and is used to easily migrate existing pipelines. This pipelet uses the mail services attached to the current application.
CreateMail	bc_mail	Creates a new mail data object with ISML templates. It is possible to use CMS components too, with a template containing the CMS SystemPageID.
UpdateMail	bc_mail	Manipulates an existing mail. Content can be replaced with ISML template processing.
SendMail	bc_mail	This pipelet sends the email via a configured mail service. The service can send the email asynchronously; the pipelet returns a `Future` object of the `MailResult`.

Services

SendMailService	interface to provide services to send emails
MailResult	contains a sending status for each recipient; an aggregated status is also available (remember that email is an asynchronous medium, the status cannot contain any final delivery status. It is possible that the server sends a bounce message (full mailbox, unknown user))
Envelope	The envelope is an extension of the `Future` interface and allows access to the request (here `Mail` as well. In the event of a failure, the `Mail` can be extracted.

SMTP Service

General

The SMTP service is a straightforward implementation of the mail service interface. The service implementation uses the ServiceChain to provide monitoring and logging capabilities - for more information see Concept - Managed Service Framework.

`SingleOperationAdapter`	adapter builds one service chain with the configured chain elements: MailSmtpConfigurator - configures the SMTP provider (creates SMTP sessions inside of the Envelope) LogHandler - standard log element; allows logging of mails MonitorHandler - standard monitor element for external services; monitor data is available at SMC
`SmtpProvider`	send mails to an external SMTP server. Class is reused at PersistentMailService.

SingleOperationAdapter

adapter builds one service chain with the configured chain elements:

MailSmtpConfigurator - configures the SMTP provider (creates SMTP sessions inside of the Envelope)
LogHandler - standard log element; allows logging of mails
MonitorHandler - standard monitor element for external services; monitor data is available at SMC

SmtpProvider

send mails to an external SMTP server. Class is reused at PersistentMailService.

Usage of SingleOperationAdapter

The SingleOperation adapter uses the service chain to provide logging and monitoring (usage of ChainElementID configuration).

There are two methods which are important for the use of the SingleOperationAdapter:

Method	Function
`setExecutor(ExecutorService<Q, A> executor)`	the executor communicates with the external system and stores any information at the process envelope
`Envelope<Q, A> invoke(Q question)`	triggers the execution of the chain and the execution of the executor at the end
`getExecutor()`	returns the current configured executor (null - the configuration definition does not contain `"Service.classSender"`)

    static class Adapter extends SingleOperationAdapter<Mail, MailResult> implements SendMailService
    {
        public Adapter(ServiceConfigurationBO serviceConfiguration) throws ConfigurationException
        {
            super(serviceConfiguration, SendMailService.class, METHOD_SEND);
            if (getExecutor() == null)
            {
                setExecutor(new SmtpProvider());
            }
        }

        @Override
        public String getServiceID()
        {
            return getServiceConfiguration().getName();
        }

        @Override
        public Envelope<Mail, MailResult> sendMail(Mail mail)
        {
            return invoke(mail);
        }

    }

Persistent Mail Service

The persistent mail service is an extension to the SMTP mail service. The service provides a configuration of the behavior. The options are defined as constants at MailConstants.

Option	Description
all	Stores all emails and email results at the database, but tries to send the email to the external SMTP service.
onerror	Stores emails which are failed to send to the external SMTP service.
no	Does not store any emails in the database. This option is comparable to the SmtpService.
persist	Stores emails in the database without sending any emails. This option replaces the SmtpProvider with the `PersistentMailProvider`. This provider can only store the emails at the database.

Note

The MailSendJob retries to send the failed emails. The option persist indirectly disables this job. An additional project-specific job is necessary to send such persistent emails directly (without the configured mail service).

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents