Email connector methods

  • Release version: Zurich
  • Updated July 31, 2025
  • 5 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Email Connector Methods

    The Email connector methods enable ServiceNow customers to integrate email functionalities into their automations by retrieving, sending, replying to emails, and managing attachments. The essential first step is to configure the connection to the mail server using theSetConfigmethod. Subsequent methods then operate on email messages accessed through this connection.

    Show full answer Show less

    These methods support handling multiple emails via iteration (using For Each or For Loop components) since some methods operate on single messages at a time.

    Key Methods and Their Practical Uses

    • SetConfig: Establishes the connection to your mail server by specifying server details, login credentials, ports, and security settings. This method must be executed before any email operations. Note that Gmail access is not supported by default and requires custom server entries.
    • GetMails: Retrieves a collection of emails from a specified IMAP folder (default is Inbox), with options to filter for read or unread messages. The output is an object containing messages for further processing.
    • MarkAsRead / MarkAsUnread: Marks specified messages in a folder as read or unread, respectively, using the message object and folder name.
    • ReadMail: Extracts details from a single email message including subject, body, sender, CC, BCC, and attachment count.
    • ReplyMail: Sends an automatic reply to a message with options to reply to all recipients, include BCC, specify message body (plain text or HTML), and add attachments by file path.
    • SaveAllAttachments: Downloads all attachments from a specified email message to a local directory.
    • SendMail: Sends an email with configurable recipients (To, CC, BCC), subject, body (plain text or HTML), and attachments. The sender address is set via the SetConfig method.

    Practical Considerations for ServiceNow Customers

    • Always begin with SetConfig to ensure your automation can connect to the mail server.
    • When processing multiple emails, use looping components to handle each message individually for methods like ReadMail, ReplyMail, and SaveAllAttachments.
    • Specify exact folder paths using backslashes for nested folders (e.g., Project\Meetings).
    • Attachments are managed by specifying file paths without quotes and separating multiple attachments with commas.
    • Gmail servers are set by default but not supported; update these server parameters to match your mail service provider.

    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.

    SetConfig

    Sets up the connection to the mail server so that the automation can work with messages.
    Note:
    You must run this method before running any other methods in the Email connector.

    For information about how to set the parameters, see Configure port properties.

    Table 1. SetConfig method parameters
    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.

    Table 2. GetMails method parameters
    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.

    Table 3. MarkAsRead method parameters
    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.

    Table 4. MarkAsRead method parameters
    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.

    Table 5. ReadMail method parameters
    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.

    Table 6. ReplyMail method parameters
    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:
    1. Paste the path to the file in the field.
    2. Remove the quotes enclosing the path.

    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.

    Table 7. SaveAllAttachments method parameters
    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

    Sends a message. Use the parameters to set the body of the message and other details. You can include attachments.
    Note:
    Use the SetConfig method to set the From address.

    For information about how to set the parameters, see Configure port properties.

    Table 8. SendMail method parameters
    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:
    1. Paste the path to the file in the field.
    2. Remove the quotes enclosing the path.

    To include multiple attachments, separate the paths by commas.