Email

the email connector facilitates the automation of email management and analysis tasks, supporting essential email protocols and enabling seamless integration with email services the email connector for swimlane turbine provides a comprehensive suite of actions for email management and automation within security workflows it enables users to retrieve email metadata, manage email attachments with precision, ingest emails for automated processing, and send emails directly from the swimlane platform by integrating with the email connector, swimlane turbine users can streamline their incident response and automate routine email related tasks, enhancing the efficiency and effectiveness of their security operations prerequisites to effectively utilize the email connector within swimlane turbine, ensure you have the following prerequisites oauth2 client credentials for microsoft graph api authentication with the following parameters host the server hosting the email service client id the unique identifier for your application client secret a secret key used to authenticate your application 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 app requires custom authentication for other email services with the following parameters host the server hosting the email service user the username required to access 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 imap4 or pop3 server (configure protocol in the custom asset) 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 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 protocol protocol used for ingesting emails imap4 supports multiple mailboxes and filters; pop3 uses a single inbox and fetches all messages 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 pop3 port port of the pop3 server (typically 995 for ssl, 110 for non ssl) 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, including headers and relevant details, 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 input example {"email attachment" \["string"],"rfc882"\ true,"remove raw content"\ true,"remove content id"\ true,"remove raw headers"\ true,"exclude extensions" "string","include only extensions" "string","remove embedded images"\ true,"ignore errors"\ true,"use cid names"\ true} 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 metadata result string response data metadata attachments sha1 string response data metadata attachments md5 string response data metadata attach info array response data metadata attach info content type string response data metadata attach info content disposition string response data metadata attach info content transfer encoding string response data metadata attach info content id string response data metadata attach info x attachment id string response data metadata headers string response data metadata recipients string response data metadata subject string response data metadata text body string response data metadata html body string response data metadata type string response data metadata attachments sha256 string response data metadata cc string response data metadata bcc string response data metadata raw headers string response data metadata raw content string response data metadata headers json string response data output 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 bo get email metadata attachments in list retrieve metadata for email attachments, including names, types, and sizes, based on the specified 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 input example {"email attachment" \["string"],"rfc882"\ true,"remove raw content"\ true,"remove raw headers"\ true,"exclude extensions" "string","include only extensions" "string","remove embedded images"\ true,"ignore errors"\ true,"use cid names"\ true} 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 metadata result string response data metadata attachments sha1 string response data metadata attachments md5 string response data metadata attach info array response data metadata attach info content type string response data metadata attach info content disposition string response data metadata attach info content transfer encoding string response data metadata attach info content id string response data metadata attach info x attachment id string response data metadata headers string response data metadata recipients string response data metadata subject string response data metadata text body string response data metadata html body string response data metadata type string response data metadata attachments sha256 string response data metadata cc string response data metadata bcc string response data metadata raw headers string response data metadata raw content string response data metadata headers json string response data output 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 bo ingest email automatically processes and analyzes incoming emails for response in swimlane, supporting imap4 (with mailbox and filter) and pop3 protocols endpoint method get input argument name type required description mailbox string optional mailbox to ingest emails from (imap4 only; ignored for pop3) filter string optional filter to apply when ingesting emails (imap4 only; ignored for pop3) mark as read boolean optional mark ingested emails as read (imap4 only; not supported for pop3) input example {"mailbox" "inbox","filter" "all","mark as read"\ true} send email initiates the sending of an email from a specified address to one or more recipients, requiring '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 attachments file string optional parameter for send email attachments file name string optional name of the resource input example {"subject" "hello world!","from" "sender\@example com","to" \["recipient1\@example com","recipient2\@example com"],"cc" \["cc recipient\@example com"],"bcc" \["bcc recipient\@example com"],"in reply to" "<123456\@example com>","reply to" "reply\@example com","references" \["123456\@example com","789012\@example com"],"text msg" "this is the plain text version of the message ","html msg" "\<p>this is the \<b>html\</b> version of the message \</p>","headers override" "{'x my header' 'value'}"} output parameter type description success boolean whether the operation was successful output example {"success"\ true} response headers header description example content type the media type of the resource application/json date the date and time at which the message was originated thu, 01 jan 2024 00 00 00 gmt