Content Script Extension for Mail

Using the extension

This section describes how to use the mail API to send and retrieve emails from an email service provider. The main Script API object you use is the CSEmail object, which you obtain from the mail service by calling the mail.create Script API method.

def email = mail.create('Hello Jane, how are you doing today?')
                .to('jane.doe@example.com')
                .from('john.doe@example.com')
                .subject('Hello Jane')
                .send()

You can also create an empty email and build it step by step:

def email = mail.create()
                .to('jane.doe@example.com', 'john.doe@example.com')
                .cc('manager@example.com')
                .from('sender@example.com')
                .subject('Meeting Reminder')
                .msg('<h1>Reminder</h1><p>Don\'t forget about the meeting tomorrow.</p>')
                .send()

To attach files or Content Server documents to an email:

def document = docman.getNode(12345)
def email = mail.create('Please find the attached document.')
                .to('recipient@example.com')
                .subject('Document Attachment')
                .attach(document)
                .send()

To send emails to Content Server users or groups:

def user = users.getUser('jane.doe')
def email = mail.create('Hello from Content Script!')
                .distribute(user)
                .subject('Welcome')
                .send()

To fetch emails from a mailbox folder:

def messages = mail.fetchMessages('INBOX', 10, false, true)
messages.each { message ->
    log.info("Subject: ${message.subject}")
    log.info("From: ${message.from}")
    log.info("Content: ${message.htmlContent ?: message.plainContent}")
}

Email profile configuration

The mail service supports one or more configuration profiles that define the integration settings with the provider service endpoints. Each profile can be configured with specific SMTP and IMAP/POP3 settings, allowing you to use different email providers or accounts within the same Content Script environment.

To use a specific profile when sending emails, you can pass the profile ID to the send method:

def email = mail.create('Message content')
                .to('recipient@example.com')
                .subject('Subject')
mail.send(email, 'customProfile')

When fetching messages, you can also specify a profile:

def messages = mail.fetchMessages('INBOX', 10, false, true, 'customProfile')

The following table lists all available configuration properties for mail profiles. Properties are prefixed with the profile ID (e.g., amcs.mail.smtpHostName.default for the default profile, or amcs.mail.smtpHostName.customProfile for a custom profile). The Notes column indicates whether each property is current (recommended) or legacy (still supported for backward compatibility; prefer using an Auth profile instead of legacy inline credentials).

Property Name	Description	Default Value	Notes
amcs.mail.authProfile.{profileID}	Authentication profile ID. If set, the mail profile uses the Auth Service profile with this name for credentials (OAuth tokens or BASIC). Mail-specific settings (hosts, ports, smtpUsername for identity) remain here; secrets are in the Auth Service.		Current (recommended)
amcs.mail.activeProfiles	Comma separated list of active MAIL profiles	default	Current
amcs.mail.smtpHostName.{profileID}	The SMTP server hostname or IP address	127.0.0.1	Current
amcs.mail.smtpHostPort.{profileID}	The SMTP port number	25	Current
amcs.mail.smtpSetStartTLS.{profileID}	Enables SMTP_TLS transport strategy: plaintext SMTP with STARTTLS upgrade (mail.smtp.starttls.enable=true)	false	Current
amcs.mail.smtpSetStartTLSRequired.{profileID}	Set or disable the required STARTTLS encryption (mail.smtp.starttls.required)	false	Current
amcs.mail.smtpSetSSLOnConnect.{profileID}	Enables SMTPS transport strategy: SMTP entirely encapsulated by TLS (mail.transport.protocol=smtps)	false	Current
amcs.mail.smtpUsername.{profileID}	SMTP identity: with OAuth this is the user email address; with legacy BASIC auth this is the SMTP username.		Current (identity); also used by legacy inline BASIC
amcs.mail.smtpPassword.{profileID}	SMTP server authentication password (hidden field). Used only when using legacy inline BASIC authentication (smtpSimpleAuthentication=true).		Legacy (inline BASIC)
amcs.mail.smtpSimpleAuthentication.{profileID}	Set 'true' to use inline SMTP username/password for this profile instead of an Auth profile or inline OAuth.	false	Legacy (inline BASIC)
amcs.mail.smtpOAuth2.{profileID}	Enables SMTP_OAUTH2 transport strategy (mail.smtp.auth.mechanisms=XOAUTH2) using inline OAuth settings below instead of an Auth profile.	false	Legacy (inline OAuth)
amcs.mail.smtpOAuth2.provider.{profileID}	OAuth2 Email Service Provider (google, microsoft, custom)	custom	Legacy (inline OAuth)
amcs.mail.smtpOAuth2.clientid.{profileID}	OAuth2 Email Application's Client ID		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.clientsecret.{profileID}	OAuth2 Email Application's Client Secret (hidden field)		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.tenantid.{profileID}	OAuth2 Email Application's Tenant (Microsoft)		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.authUrl.{profileID}	OAuth2 Email Application's Authorization Base URL		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.tokenUrl.{profileID}	OAuth2 Email Application's Token URL		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.redirectUrl.{profileID}	OAuth2 Email Application's redirect URL		Legacy (inline OAuth)
amcs.mail.smtpOAuth2.scope.{profileID}	OAuth2 Email Application's scope		Legacy (inline OAuth)
amcs.mail.debug.{profileID}	Setting to true will enable the display of debug information	false	Current
amcs.mail.sessionProperties.{profileID}	A comma separated list of session properties. Properties are defined as: propname@value		Current
amcs.mail.mailProtocol.{profileID}	The protocol used to fetch emails: pop3, pop3s, imap, imaps	imaps	Current
amcs.mail.mailHostName.{profileID}	The inbox email hostname (IMAP/POP3)		Current
amcs.mail.mailHostPort.{profileID}	The inbox email port (IMAP/POP3)		Current
amcs.mail.smtpSSLProtocols.{profileID}	SSL/TLS protocols enabled for SSL/TLS connections (e.g. TLSv1.2). Whitespace-separated list acceptable to SSLSocket.setEnabledProtocols.	TLSv1.2	Current
amcs.mail.smtpVerifyServerIdentity.{profileID}	Configures the current session to verify/not verify the server's identity on an SSL connection	true	Current

Authentication and Auth Profiles

Authentication for each mail profile is handled in one of two ways:

1. Auth profile (recommended) – The mail profile is linked to a named profile in the Auth Service. Credentials (OAuth tokens or BASIC username/password) are stored and managed by the Auth Service. The mail service only holds transport settings (hosts, ports, protocols) and the identity (e.g. email address for OAuth).
2. Legacy inline settings – OAuth or BASIC credentials are defined directly in the mail service configuration. This path is still supported for backward compatibility but is deprecated.

When you set amcs.mail.authProfile.<profileID> to a non-empty value (e.g. google), the mail service loads the Auth Service profile with that same ID. The Auth Service must have a profile with that name configured (client ID, client secret, tenant ID where applicable, etc.). Mail-specific settings (SMTP/IMAP host, port, protocol, SMTP username for OAuth identity) remain in the mail configuration.

Linking mail and auth profiles

For a mail profile named google, set Custom:amcs.mail.authProfile.google to google. Then configure the Auth Service with a profile also named google (using Custom:amcs.auth.*.google keys). The mail service will use that auth profile for credentials and token handling.

Sample providers

Provider	Send	Fetch (IMAP)	Auth type
Google (Gmail)	✓	✓	OAuth 2.0
Microsoft (Office 365 / Outlook)	✓	✓	OAuth 2.0
AWS Simple Email Service (SES)	✓	—	BASIC (SMTP credentials)

• Google and Microsoft use OAuth 2.0; the Auth Service stores and refreshes tokens. You configure OAuth client ID, client secret, redirect URI, scopes, and (for Microsoft) tenant ID in the Auth profile.
• AWS SES is send-only (no IMAP). It uses SMTP with BASIC auth (username = SMTP access key, password = SMTP secret key), which can be stored in the Auth Service profile.

Configuration overview

Configuration is stored in the Module Suite Base Configuration (AnswerModules Base Configuration Custom Section).

1. Active profiles – List the mail profiles that may be used in amcs.mail.activeProfiles (e.g. default, google, microsoft, aws).
2. Auth profile link – For each mail profile that should use the Auth Service, set Custom:amcs.mail.authProfile.<profileID> to the Auth profile ID (typically the same as the mail profile name).
3. Mail settings – Configure transport and fetch settings per profile with keys such as Custom:amcs.mail.smtpHostName.<profileID>, Custom:amcs.mail.mailHostName.<profileID>, Custom:amcs.mail.smtpUsername.<profileID>, etc.
4. Auth settings – In the same Custom section, configure the Auth Service profile with keys such as Custom:amcs.auth.auth_type.<profileID>, Custom:amcs.auth.client_id.<profileID>, Custom:amcs.auth.client_secret.<profileID>, and provider-specific keys (e.g. tenant_id for Microsoft, username/password for BASIC).

Secrets (client secrets, passwords, SMTP credentials) should be stored according to your security practices; the Base Configuration supports secret placeholders and secure storage where available.

The following tables list sample configuration keys and values for different providers. Keys are defined in the Base Configuration Custom section (e.g. Custom:amcs.mail.authProfile.google).

Google (Gmail) — Send + Fetch, OAuth 2.0

Configuration key	Sample value
amcs.mail.authProfile.google	google
amcs.mail.debug.google	true
amcs.mail.mailHostName.google	imap.gmail.com
amcs.mail.mailHostPort.google	993
amcs.mail.mailProtocol.google	imaps
amcs.mail.smtpHostName.google	smtp.gmail.com
amcs.mail.smtpHostPort.google	587
amcs.mail.smtpUsername.google	user@example.com
amcs.mail.smtpSetSSLOnConnect.google	true
amcs.mail.smtpSetStartTLS.google	false
amcs.mail.smtpSetStartTLSRequired.google	false
amcs.mail.smtpSimpleAuthentication.google	false
amcs.mail.smtpSSLProtocols.google	TLSv1.2
amcs.mail.smtpVerifyServerIdentity.google	false
amcs.auth.auth_type.google	OAUTH
amcs.auth.provider.google	google
amcs.auth.auth_uri.google	https://accounts.google.com/o/oauth2/auth
amcs.auth.token_uri.google	https://oauth2.googleapis.com/token
amcs.auth.client_id.google	123456789-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.apps.googleusercontent.com
amcs.auth.client_secret.google	(secret)
amcs.auth.redirect_uri.google	https://example.com/otcs/cs
amcs.auth.scope.google	https://mail.google.com/
amcs.auth.username.google	user@example.com

Microsoft (Office 365 / Outlook) — Send + Fetch, OAuth 2.0

Configuration key	Sample value
amcs.mail.authProfile.microsoft	microsoft
amcs.mail.debug.microsoft	true
amcs.mail.mailHostName.microsoft	outlook.office365.com
amcs.mail.mailHostPort.microsoft	993
amcs.mail.mailProtocol.microsoft	imaps
amcs.mail.sessionProperties.microsoft	mail.smtp.auth.mechanisms@XOAUTH2,mail.smtp.ssl.protocols@TLSv1.2,mail.smtp.auth@true,mail.smtp.starttls.enable@true,mail.smtp.sendpartial@false,mail.smtps.sendpartial@false
amcs.mail.smtpHostName.microsoft	smtp.office365.com
amcs.mail.smtpHostPort.microsoft	587
amcs.mail.smtpUsername.microsoft	ej.doe@xample.onmicrosoft.com
amcs.mail.smtpSetSSLOnConnect.microsoft	true
amcs.mail.smtpSetStartTLS.microsoft	true
amcs.mail.smtpSetStartTLSRequired.microsoft	true
amcs.mail.smtpSimpleAuthentication.microsoft	false
amcs.mail.smtpSSLProtocols.microsoft	TLSv1.2
amcs.mail.smtpVerifyServerIdentity.microsoft	false
amcs.auth.auth_type.microsoft	OAUTH
amcs.auth.provider.microsoft	microsoft
amcs.auth.tenant_id.microsoft	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
amcs.auth.auth_uri.microsoft	https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/oauth2/v2.0/authorize
amcs.auth.token_uri.microsoft	https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/oauth2/v2.0/token
amcs.auth.client_id.microsoft	aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
amcs.auth.client_secret.microsoft	(secret)
amcs.auth.redirect_uri.microsoft	https://example.com/otcs/cs
amcs.auth.scope.microsoft	https://outlook.office.com/SMTP.Send
amcs.auth.username.microsoft	ej.doe@xample.onmicrosoft.com

AWS Simple Email Service (SES) — Send only, BASIC

Configuration key	Sample value
amcs.mail.authProfile.aws	aws
amcs.mail.debug.aws	true
amcs.mail.smtpHostName.aws	email-smtp.eu-west-1.amazonaws.com
amcs.mail.smtpHostPort.aws	25
amcs.mail.smtpSetSSLOnConnect.aws	false
amcs.mail.smtpSetStartTLS.aws	true
amcs.mail.smtpSetStartTLSRequired.aws	true
amcs.mail.smtpVerifyServerIdentity.aws	false
amcs.auth.auth_type.aws	BASIC
amcs.auth.username.aws	AKIAXXXXXXXXXXXXXXXX
amcs.auth.password.aws	(secret)

Placeholders

Sample values such as user@example.com, ej.doe@xample.onmicrosoft.com, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, and client IDs are placeholders. Replace them with your real configuration and store secrets securely.

Using the mail service in scripts

Specify the profile ID when sending or fetching so that the correct mailbox and auth profile are used:

def email = mail.create('test')
    .to('recipient@example.com')
    .from('user@example.com')
    .subject('Test message')

def res = mail.send(email, 'google')

Use the same profile ID for fetch operations when the profile supports IMAP (e.g. google, microsoft).

OAuth 2.0 configuration and authentication

When using a mail profile linked to an Auth profile with OAuth 2.0 (e.g. Google or Microsoft), you must complete the authorization flow once so the Auth Service can store tokens. The mail service then handles token refresh automatically.

The mail service supports OAuth 2.0 using the Authorization Code flow, so you can access email without storing user passwords. The flow is handled automatically once configured.

Authorization code flow

The OAuth 2.0 process has two main steps:

Step 1: Authorization and code exchange

Obtain an authorization URL and have the user authorize your application. The authorization code is captured and stored by the system through the oauthflow.groovy endpoint.

// Get the authorization URL for an OAuth-enabled profile
String applicationRedirectUrl = "${url}/runcs/am/oauthflow"
String oAuthProfileID = 'default'  // or your OAuth-enabled profile ID

// Optional: Add provider-specific parameters
def additionalParams = [
    access_type: "offline",  // For Google - requests refresh token
    prompt: "consent"        // For Google - forces consent screen
]

def authUrl = auth.getOAuthAuthorizationUrl(applicationRedirectUrl, additionalParams, oAuthProfileID)

// Display the authorization link to the user
out << """
<div>
    <p>Click the link below to authorize the OAuth application for profile '${oAuthProfileID}'.</p>
    <p><strong>IMPORTANT:</strong> You should be authenticated with the relevant user account to provide the correct authorization.</p>
    <a href="${authUrl}" target="_blank">Authorize Application</a>
</div>
"""

When the user clicks the authorization link and grants permission, they are redirected to {redirectUrl}/runcs/am/oauthflow. That endpoint:

1. Receives the authorization code from the OAuth provider
2. Exchanges it for an access token (and refresh token if available)
3. Stores the tokens securely in the system

Step 2: Using the mail API with OAuth 2.0

After the OAuth flow is complete, use any mail API method with the OAuth-enabled profile. The mail service handles token management automatically:

• If no token exists: the system exchanges the stored authorization code for a new access token
• If a valid token exists: the system uses the existing access token
• If the token is expired or close to expiration: the system refreshes the token using the refresh token (if available)

// Send email using OAuth-enabled profile
def email = mail.create('Hello from OAuth!')
                .to('recipient@example.com')
                .subject('OAuth Test')
                .send()  // Uses default profile, or specify: mail.send(email, 'oauthProfile')

// Fetch messages using OAuth-enabled profile
def messages = mail.fetchMessages('INBOX', 10, false, true, 'oauthProfile')
messages.each { message ->
    out << "<br>Subject: ${message.subject}"
}

Token management is transparent; you do not need to handle token refresh or expiration manually.

Mail service APIs

Method Summary
CSEmail	create() Creates a new empty email template
CSEmail	create(String htmlMessage) Creates a new email template with the specified HTML message body
CSEmail	create(String htmlMessage, String to) Creates a new email template with the specified HTML message body and recipient
List<Exception>	send(CSEmail template) Sends the email template using the default profile
List<Exception>	send(CSEmail template, String profileID) Sends the email template using the specified profile
List<CSEmailMessage>	fetchMessages(String folderName, int maxFetchSize, boolean shouldDeleteMessage, boolean shouldMarkAsSeen) Fetches emails from the given folder using the default profile
List<CSEmailMessage>	fetchMessages(String folderName, int maxFetchSize, boolean shouldDeleteMessage, boolean shouldMarkAsSeen, String profileID) Fetches emails from the given folder using the specified profile
String	getOAuthAuthorizationUrl(String redirectUrl, Map<String, String> additionalParameters, String profileID) Gets the OAuth2 authorization URL for the specified mail profile
Boolean	storeOAuthCode(String code, String state, String profileID) Stores the OAuth2 authorization code for the given profile

API Objects

CSEmail

Method Summary
CSEmail	to(String... to) Set the recipient email address(es)
CSEmail	cc(String cc) Set the CC recipient email address
CSEmail	bcc(String... to) Set the BCC recipient email address(es)
CSEmail	from(String address) Set the sender email address
CSEmail	subject(String aSubject) Set the email subject
CSEmail	msg(String aHtml) Set the HTML message body
CSEmail	attach(File... attachment) Attach file(s) to the email
CSEmail	attach(File attachment, String name) Attach a file with a custom name
CSEmail	attach(CSDocument... attachment) Attach Content Server document(s) to the email
CSEmail	attach(CSDocument attachment, String name) Attach a Content Server document with a custom name
CSEmail	distribute(CSMember... recipient) Set recipient(s) using CSMember objects (User, Group, or Role)
CSEmail	setCharset(String charset) Set the email character encoding
CSEmail	setHeaders(Map<String, String> headers) Set custom email headers
CSEmail	clearTo() Clear all TO recipients
CSEmail	clearCc() Clear all CC recipients
CSEmail	clearBcc() Clear all BCC recipients
List<Exception>	send() Send the email using the default profile
CSMember	getRecipient() Get the primary recipient
List<CSMember>	getRecipients() Get all recipients
void	setRecipient(CSMember recipient) Set the primary recipient using a CSMember object

CSEmailMessage

Method Summary
List<String>	getTo() Retrieves the list of recipients for this email message
List<String>	getCc() Retrieves the list of CC recipients for this email message
List<String>	getBcc() Retrieves the list of BCC recipients for this email message
String	getFrom() Retrieves the sender address for this email message
String	getReplyTo() Retrieves the reply-to address for this email message
String	getSubject() Retrieves the subject line for this email message
List<CSResource>	getAttachmentList() Retrieves the list of attachments for this email message
CSResource	findAttachmentByName(String name) Finds a specific attachment by name in this email message
CSEmailProperties	getEmailProperties() Retrieves the email properties for this message

Field Summary
CSResource	rawMessage CSResource which represents the raw EML message content
String	plainContent String which represents the plain text content of the email message
String	htmlContent String which represents the HTML content of the email message
List<CSResource>	attachmentList List of CSResource objects representing the email attachments
boolean	multipart Boolean which indicates if the email message is multipart

Summary

• Use multiple mail profiles (e.g. google, microsoft, aws) and list them in amcs.mail.activeProfiles.
• Link each mail profile to an Auth profile via amcs.mail.authProfile.<profileID> so credentials and OAuth tokens are managed by the Auth Service.
• Configure mail-specific settings (hosts, ports, protocols, SMTP username) under Custom:amcs.mail.*.<profileID> and auth-specific settings (client ID, client secret, tenant ID, etc.) under Custom:amcs.auth.*.<profileID> in the Base Configuration Custom section.
• In scripts, pass the profile ID to mail.send(...) and fetch APIs to use the desired mailbox and authentication.