Document Properties
KbidP23982
Last Modified04-Feb-2020
Added to KB05-Mar-2013
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Mail Services

1 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

2 Reference

Please also have a look at the corresponding cookbook .

3 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

3.1 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.


3.2 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.

4 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.

4.1 SMTP Service

4.1.1 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.

4.1.2 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);
        }

    }

4.2 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.

Customer Support
Knowledge Base
Product Resources
Tickets