Email connector methods

  • Release version: Yokohama
  • Updated January 30, 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 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 full answer 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.

    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.