Email connector methods
Summarize
Summary of Email connector methods
The Email connector methods in ServiceNow Yokohama release enable automation workflows to interact with email servers for retrieving, sending, replying to emails, and managing attachments. These methods require initial configuration of the mail server connection usingSetConfig. Subsequent methods operate on emails individually or as collections, allowing detailed email processing within automation.
Show less
Key Features
- SetConfig: Configures connection to the mail server with parameters like username, password, SMTP/IMAP servers and ports, and SSL usage. This setup must precede all other email operations.
- GetMails: Retrieves emails from a specified IMAP folder with options to filter for read or unread messages, returning a collection object for processing.
- MarkAsRead/MarkAsUnread: Marks specific messages as read or unread in designated IMAP folders using the email object.
- ReadMail: Extracts detailed information from a single email message, including subject, body, sender, CC/BCC recipients, and attachment count.
- ReplyMail: Sends automated replies to an email with options to reply to all recipients, include BCC, format the body as HTML, and attach files.
- SaveAllAttachments: Downloads all attachments from an email message to a specified local directory.
- SendMail: Sends new email messages with customizable recipients (To, CC, BCC), subject, body content (HTML option), and attachments.
Practical Considerations for ServiceNow Customers
- Always initiate email automations by running SetConfig to establish server connectivity and credential authentication.
- When processing multiple emails retrieved by GetMails, use looping constructs such as For Each or For Loop to handle each email individually with methods like ReadMail or ReplyMail.
- Attachment handling supports file path inputs for sending or saving files, with multiple attachments separated by commas.
- Note that default SMTP/IMAP server values reference Gmail but do not support Gmail access; update these parameters accordingly for your mail server.
- Configuring port properties correctly is essential for method parameters; refer to port configuration guidance when setting up each method.
Expected Outcomes
By leveraging these Email connector methods, ServiceNow customers can automate comprehensive email interactions within workflows, including fetching emails for processing, replying or sending emails programmatically, and managing attachments efficiently. This facilitates streamlined email-based automation use cases such as notifications, ticket updates, or integration with external email systems.
The methods in the Email connector retrieve, send, and reply to email messages, and can download attachments. Use the SetConfig method first to set up the connection to your mail server.
Use the SetConfig method to configure the mail server properties and access credentials. This method must precede all the other Email connector methods in the automation.
The GetMails method retrieves messages from the mail server and passes them to other methods as an object that contains one or more messages. The ReadMail, ReplyMail, and SaveAllAttachments methods operate on a single message at a time. When these methods receive an object that contains more than one message, the automation must use a For Each or For Loop method to iterate each message in the collection.
- For information about how to use the For Each method, see Use the For Each component.
- For information about how to use the For Loop method, see Use the For Loop component.
SetConfig
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| Username | User name to log in to the mail server | Data In | String | (none) | Yes | |
| Password | Password to log in to the mail server | Data In | String | (none) | Yes | |
| UseDefaultCredentials | Sends the default credentials of the currently logged-in user to the SMTP server. | Data In | Boolean | False | No | |
| SmtpMailServer | Name of the SMTP server | Data In | String | smtp.gmail.com | No | Access to Gmail by using the Email connector is not currently supported. Make sure to change the default value. |
| ImapMailServer | Name of the IMAP server | Data In | String | imap.gmail.com | No | Access to Gmail by using the Email connector is not currently supported. Make sure to change the default value. |
| SSL | Use the Secure Socket Layer protocol | Data In | Boolean | True | No | |
| SmtpPort | SMTP port number | Data In | Integer | 587 | No | |
| ImapPort | IMAP port number | Data In | Integer | 993 | No |
GetMails
Returns messages from the mail server for use by other methods. You can set the method to retrieve either read (seen) or unread (unseen) messages and specify the folder that they're gathered.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| FolderName | Name of the IMAP folder that the method fetches the collection (for example, Inbox) | Data in | String | Inbox | Yes | To specify a nested IMAP folder, enter the folder hierarchy by using backslashes (for example, Project\Meetings) |
| Filter | Set to get only unread (Unseen) or read (Seen) messages | Data in | FilterMode | Unseen | Yes | |
| Return | Returns the mail collection as an object | Data out | Object | Object | Yes |
MarkAsRead
Marks messages from a specified folder as read.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| MailObject | The email object based on which the corresponding message is marked as read | Data in | Object | Object | Yes | |
| FolderName | Name of the IMAP folder that the email object is fetched | Data in | String | Inbox | Yes | To specify a nested IMAP folder, enter the folder hierarchy by using backslashes (for example, Project\Meetings) |
MarkAsUnread
Marks messages from a specified folder as unread.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| MailObject | The email object based on the corresponding email that is marked as unread. | Data in | Object | Object | Yes | |
| FolderName | Name of the IMAP folder that the email object is fetched. | Data in | String | Inbox | Yes | To specify a nested IMAP folder, enter the folder hierarchy by using backslashes (for example, Project\Meetings) |
ReadMail
Reads a message and returns its details, including subject, body, sender (from), recipients in the CC field, recipients in the BCC field, and the number of attachments.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? |
|---|---|---|---|---|---|
| MailObject | MailObject that gives the details of the last message received | Data in | Object | Object | Yes |
| Subject | Subject of the message | Data out | String | None | No |
| Body | Body of the message | Data out | String | None | No |
| Sender | Sender of the message | Data out | String | None | No |
| CC | Recipients marked in CC | Data out | String | None | No |
| BCC | Recipients marked in BCC | Data out | String | None | No |
| AttachmentsCount | Number of attachments in the message | Data out | Integer | None | No |
ReplyMail
Automatically replies to a message. Use the parameters to set the body of the message and other details. You can include attachments.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| MailObject | Message object containing the message details | Data in | Object | Object | Yes | |
| ReplyToAll | Replies to all recipients in the To and CC fields of the message | Data in | Boolean | False | No | |
| BCC | Replies to all recipients in the BCC field of the message | Data in | String | None | No | |
| Body | Body of the reply message | Data in | String | None | No | |
| IsHtmlBody | Option to indicate whether the reply body is in HTML format | Data in | Boolean | False | No | |
| Attachments | Attachments to the reply message | Data in | String | None | No | To attach a file:
To include multiple attachments, separate the paths by commas. |
SaveAllAttachments
Saves all attachments from a message to the local drive.
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? |
|---|---|---|---|---|---|
| MailObject | Message that the method downloads the attachments from | Data In | Object | Object | Yes |
| FolderPath | Path of the directory to which the attachments are downloaded | Data In | String | None | Yes |
SendMail
For information about how to set the parameters, see Configure port properties.
| Parameter | Description | Data port type | Data type | Default value | Required? | Notes |
|---|---|---|---|---|---|---|
| ToAddress | Address to which to send the message | Data in | String | None | Yes | |
| CC | Addresses to include in the CC field | Data in | String | None | No | |
| BCC | Addresses to include in the BCC field | Data in | String | None | No | |
| Subject | Message subject | Data in | String | None | No | |
| Body | Message body | Data in | String | None | No | |
| IsHtmlBody | Option to indicate whether the reply body is in HTML format | Data in | String | False | No | |
| Attachments | Message attachments | Data in | String | None | No | To attach a file:
To include multiple attachments, separate the paths by commas. |