23 min
the email connector facilitates the automation of email processing and communication within the swimlane platform, enabling seamless integration with email services the email connector for swimlane turbine provides a comprehensive suite of actions to automate and streamline email related tasks within security workflows it enables users to retrieve email metadata, manage email attachments, ingest emails for analysis, and send emails directly from the swimlane platform by integrating with email, swimlane turbine users can enhance incident response, automate threat intelligence gathering, and facilitate seamless communication within security operations prerequisites to effectively utilize the email connector for swimlane, ensure you have the following prerequisites in place oauth2 client credentials and refresh token for microsoft graph api integration, with the following parameters host the endpoint url for the email service client id the application's identifier registered with the email service client secret the application's secret key for authentication tenant id the directory tenant that you want to request permission from refresh token token used to obtain a new access token when the current one expires scopes permissions the application needs to function correctly custom authentication setup (if required), with the following parameters host the endpoint url for the custom email service user the username required for accessing the email service authentication for oauth2 refresh token grant credentials for microsoft graph api authentication oauth 2 0 refresh token grant, which requires a 'refresh token', 'tenant id', 'client id' and 'client secret' use this auth with accounts which have mfa enabled to generate a refresh token please follow the instructions below in step 3 of the above mentioned setup instructions, please provide a 'redirect uri' and select the platform as 'web', before clicking on 'register' at the the bottom proceed with the remaining steps to generate 'client id', 'tenant id' and 'client secret' the swimlane team will provide a python script and instructions on how to use the script to generate the refresh token capabilities the swimlane email connector has the following capabilities ingest emails from imap server send email to smtp server the action send email allows to override the headers of the email however, "txt msg", "html msg", "from" and "to" are not allowed to be overridden the "override headers" field needs to be a json valid string { "subject" "new subject", "x custom header" "custom header value", "bcc" "custom\@swimlane com" } to use oauth2 refresh token grant credentials for microsoft graph api authentication open the microsoft 365 admin center https //admin microsoft com/#/homepage and go to users > active users select the user, and in the flyout that appears, select mail in the email apps section, select manage email apps verify the authenticated smtp setting unchecked = disabled, checked = enabled when you're finished, select save changes common errors \[errno 101] network is unreachable this can be caused by choosing the wrong verify ssl option in the asset the port changes depending on whether ssl is enabled or not, so if you try to connect to a server that only allows ssl connections with verify ssl disabled, it could cause this error configurations imap/smtp authentication configuration parameters parameter description type required host the host of the email server string required user user string required password password string optional use ssl use ssl boolean optional imap starttls enable starttls to upgrade the connection to ssl/tls boolean optional imap port port of the imap4 server number optional smtp starttls enable starttls to upgrade the connection to ssl/tls boolean optional smtp port port of the smtp server number optional swimlane email oauth 2 0 client credentials authenticates using oauth 2 0 client credentials and refresh token this is used for microsoft graph api configuration parameters parameter description type required host the host of the email server string required tenant id the tenant id string required client id the client id string required client secret the client secret string required refresh token the refresh token string required scope permission scopes for this action array required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions get email metadata retrieve metadata, such as headers and other pertinent information, for a specified email attachment endpoint method get input argument name type required description email attachment array required file to be attached rfc882 boolean optional check if emails adhere to rfc882 format remove raw content boolean optional remove the raw content key of the email from the outputs defaults to false remove content id boolean optional removes the content id property from the raw content remove raw headers boolean optional remove the raw headers key of the email from the response defaults to false exclude extensions string optional a csv of extensions you would like to ignore useful if image files are being parsed out of email footer as attachments default is jp(e)g, png, gif filling this value will overwrite existing default include only extensions string optional only include these extension types from the attachments of the parsed email overrides excluded extensions defaults to none remove embedded images boolean optional if true, removes all image elements from text and html bodies defaults to false ignore errors boolean optional ignore errors parsing an email defaults to false use cid names boolean optional use cids as filenames in eml files output parameter type description status code number http status code of the response headers object http headers for the request reason string response reason phrase metadata object response data result string result of the operation attachments sha1 string output field attachments sha1 attachments md5 string output field attachments md5 attach info array output field attach info content type string type of the resource content disposition string response content content transfer encoding string response content content id string unique identifier x attachment id string unique identifier headers string http headers for the request recipients string output field recipients subject string output field subject text body string request body data html body string request body data type string type of the resource attachments sha256 string output field attachments sha256 cc string output field cc bcc string output field bcc raw headers string http headers for the request raw content string response content headers json string http headers for the request example \[ { "status code" 200, "headers" null, "reason" "ok", "metadata" { "result" "success", "attachments sha1" "28a0ab5e6b6eb3d00a686a6a6c509a02feb506b8", "attachments md5" "d223b0dbacbddfa3c37047f2573c3b11", "attach info" \[], "headers" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14) b ", "recipients" "pov\@swimlaneintegrations onmicrosoft com", "subject" "sample 1", "text body" "here is an attachment and some links\r\n\r\nhttps //www exoduspoint com\r\n\r\nhttps //w\ ", "html body" "\<meta http equiv=\\"content type\\" content=\\"text/html; charset=utf 8\\">\<div dir=\\"ltr ", "type" "eml", "attachments sha256" "2a730ce1ef15e3619844ea40ff5539da6a58ab35129424c84f66dd7128c96ab1", "cc" "", "bcc" "", "raw headers" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14)\r\n ", "raw content" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14)\n " }, "attachments" \[ {} ] } ] get email metadata attachments in list retrieve metadata of email attachments, such as names, types, and sizes, using the provided email attachment input endpoint method get input argument name type required description email attachment array required file to be attached rfc882 boolean optional check if emails adhere to rfc882 format remove raw content boolean optional remove the raw content key of the email from the outputs defaults to false remove raw headers boolean optional remove the raw headers key of the email from the response defaults to false exclude extensions string optional a csv of extensions you would like to ignore useful if image files are being parsed out of email footer as attachments default is jp(e)g, png, gif filling this value will overwrite existing default include only extensions string optional only include these extension types from the attachments of the parsed email overrides excluded extensions defaults to none remove embedded images boolean optional if true, removes all image elements from text and html bodies defaults to false ignore errors boolean optional ignore errors parsing an email defaults to false use cid names boolean optional use cids as filenames in eml files output parameter type description status code number http status code of the response headers object http headers for the request reason string response reason phrase metadata object response data result string result of the operation attachments sha1 string output field attachments sha1 attachments md5 string output field attachments md5 attach info array output field attach info content type string type of the resource content disposition string response content content transfer encoding string response content content id string unique identifier x attachment id string unique identifier headers string http headers for the request recipients string output field recipients subject string output field subject text body string request body data html body string request body data type string type of the resource attachments sha256 string output field attachments sha256 cc string output field cc bcc string output field bcc raw headers string http headers for the request raw content string response content headers json string http headers for the request example \[ { "status code" 200, "headers" null, "reason" "ok", "metadata" { "result" "success", "attachments sha1" "28a0ab5e6b6eb3d00a686a6a6c509a02feb506b8", "attachments md5" "d223b0dbacbddfa3c37047f2573c3b11", "attach info" \[], "headers" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14) b ", "recipients" "pov\@swimlaneintegrations onmicrosoft com", "subject" "sample 1", "text body" "here is an attachment and some links\r\n\r\nhttps //www exoduspoint com\r\n\r\nhttps //w\ ", "html body" "\<meta http equiv=\\"content type\\" content=\\"text/html; charset=utf 8\\">\<div dir=\\"ltr ", "type" "eml", "attachments sha256" "2a730ce1ef15e3619844ea40ff5539da6a58ab35129424c84f66dd7128c96ab1", "cc" "", "bcc" "", "raw headers" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14)\r\n ", "raw content" "received from ia0pr14mb6188 namprd14 prod outlook com (2603 10b6 208 440 14)\n " }, "attachments" \[ {} ] } ] ingest email automatically processes incoming emails for analysis and response within the swimlane platform endpoint method get input argument name type required description mailbox string optional mailbox to ingest emails from filter string optional filter to apply when ingesting emails mark as read boolean optional mailbox to ingest emails from send email initiates the sending of an email from a specified address to one or more recipients, with required 'from' and 'to' fields endpoint method get input argument name type required description subject string optional parameter for send email from string required parameter for send email to array required parameter for send email cc array optional parameter for send email bcc array optional parameter for send email in reply to string optional parameter for send email reply to string optional parameter for send email references array optional parameter for send email text msg string optional parameter for send email html msg string optional parameter for send email headers override string optional http headers for the request attachments array optional files to be attached file string optional parameter for send email file name string optional name of the resource output parameter type description success boolean whether the operation was successful example \[ { "success" true } ]