Document Properties
- Intershop 7.0
- Intershop 7.2
- Intershop 7.4
- Intershop 7.4 CI
- ICM 7.7
- ICM 7.9
- ICM 11
- ICM 13
- Intershop 7.1
- Intershop 7.3
- Intershop 7.5
- ICM 7.6
- ICM 7.8
- ICM 7.10
- ICM 12
- ICM 14
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 |
References
Service-Independent Artifacts
Service-independent artifacts are:
Interfaces defining an e-mail as data object: Mail, MailAttachment, MailReceiver
Pipelets to create and send an e-mail
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 e-mail via a configured mail service. The service can send the e-mail asynchronously; the pipelet returns a |
Services
SendMailService | Interface to provide services to send e-mails |
|---|---|
MailResult | Contains a sending status for each recipient; an aggregated status is also available (remember that e-mail 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 |
SMTP Service
General
The SMTP service is an 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.
| The adapter builds one service chain with the configured chain elements:
|
|---|---|
| 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 |
|---|---|
| the executor communicates with the external system and stores any information at the process envelope |
| triggers the execution of the chain and the execution of the executor at the end |
| returns the current configured executor (null - the configuration definition does not contain |
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 e-mails and e-mail results at the database, but tries to send the e-mail to the external SMTP service. |
onerror | Stores e-mails which are failed to send to the external SMTP service. |
no | Does not store any e-mails in the database. This option is comparable to the SmtpService. |
persist | Stores e-mails in the database without sending any e-mails. This option replaces the SmtpProvider with the |
Note
The MailSendJob retries to send failed e-mails. The option persist indirectly disables this job. An additional project-specific job is necessary to send such persistent e-mails directly (without the configured mail service).
Azure Mail Service
This section applies to ICM versions 7.10.41.19-LTS to 7.10.x.x-LTS and to ICM 14.3.0 and later.
The Azure mail service is an extension to the SMTP mail service. It also sends e-mails using the SMTP protocol but uses the XOAuth2 authentication instead of basic authentication. This service is tightly coupled to Azure Entra ID for authentication and token retrieval. After the token retrieval, the e-mail is sent using Microsoft Outlook 365. The Azure mail service requires configuring some additional properties:
Property | Description | Mandatory(🔴)/Optional(⚪) | Default value |
|---|---|---|---|
Client-ID | The Client-ID for the Client Credentials Flow | 🔴 | |
Client-Secret | The Client-Secret for the Client Credentials Flow | 🔴 | |
Tenant-ID | The Tenant-ID for the Client Credentials Flow | 🔴 | |
Authority | The Authority for the Client Credentials Flow | ⚪ |
|
Scopes | The Scopes for the Client Credentials Flow | ⚪ |
|
SMTP Username | SMTP user name/e-mail address (mostly mail-from-address) | 🔴 | |
SMTP Server Hostname | SMTP server host name | ⚪ |
|
In addition to the two cartridges mentioned in the Introduction, the Azure mail service is implemented in the cartridge az_mail_azure.
For further documentation about the configuration in Azure, see Use SMTP with XOAUTH2 on Microsoft 365/Exchange Online/Office Outlook 365 with a service principal.
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 Website, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.