RPA.Email.ImapSmtp library | Robocorp documentation

RPA.Email.ImapSmtp

Add Gmail Labels

Add GMail labels to messages matching criterion and if given, source folder

Arguments

Argument	Type	Default value	Description
labels		null	comma separated list of labels to add
criterion		null	label messages matching criterion
source_folder	str	None	look for messages in this folder, default all folders

param criterion:
param labels:	comma separated list of labels to add
	label messages matching criterion
param source_folder:
	look for messages in this folder, default all folders
return:	status of the operation

Examples

Add Gmail Labels customer1 SUBJECT "order confirmation" Add Gmail Labels wip SUBJECT "order confirmation" customerfolder

Authorize

Authorize user to SMTP and IMAP servers.

Arguments

Argument	Type	Default value	Description
account	str, None	None	user account as string, defaults to None
password	str, None	None	user password as string, defaults to None
smtp_server	str, None	None	SMTP server address, defaults to None
imap_server	str, None	None	IMAP server address, defaults to None
smtp_port	int, None	None	SMTP server port, defaults to None (587 for SMTP)
imap_port	int, None	None	IMAP server port, defaults to None
is_oauth	bool	False	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

param smtp_server:
param account:	user account as string, defaults to None
param password:	user password as string, defaults to None
	SMTP server address, defaults to None
param imap_server:
	IMAP server address, defaults to None
param smtp_port:
	SMTP server port, defaults to None (587 for SMTP)
param imap_port:
	IMAP server port, defaults to None
param is_oauth:	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

Will use separately set credentials or those given in keyword call.

Examples

Authorize ${username} ${password} smtp_server=smtp.gmail.com smtp_port=587

Authorize Imap

Authorize to IMAP server.

Arguments

Argument	Type	Default value	Description
account	str, None	None	IMAP account name, defaults to None
password	str, None	None	IMAP account password, defaults to None
imap_server	str, None	None	IMAP server address, defaults to None
imap_port	int, None	None	IMAP server port, defaults to None
is_oauth	bool	False	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

param imap_server:
param account:	IMAP account name, defaults to None
param password:	IMAP account password, defaults to None
	IMAP server address, defaults to None
param imap_port:
	IMAP server port, defaults to None
param is_oauth:	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

Can be called without giving any parameters if library has been initialized with necessary information and/or keyword Set Credentials has been called.

Examples

Authorize IMAP ${username} ${password} imap.gmail.com 993

Authorize Smtp

Authorize to SMTP server.

Arguments

Argument	Type	Default value	Description
account	str, None	None	SMTP account name, defaults to None
password	str, None	None	SMTP account password, defaults to None
smtp_server	str, None	None	SMTP server address, defaults to None
smtp_port	int, None	None	SMTP server port, defaults to None (587 for SMTP)
is_oauth	bool	False	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

param smtp_server:
param account:	SMTP account name, defaults to None
param password:	SMTP account password, defaults to None
	SMTP server address, defaults to None
param smtp_port:
	SMTP server port, defaults to None (587 for SMTP)
param is_oauth:	Use XOAUTH2 protocol with a base64 encoded OAuth2 string as password

Can be called without giving any parameters if library has been initialized with necessary information and/or keyword Set Credentials has been called.

Examples

Authorize SMTP ${username} ${password} smtp.gmail.com 587

Convert Eml File Into Message

Converts EML file into message dictionary.

Arguments

Argument	Type	Default value	Description
eml_filepath	str	null	filepath to the EML file
save_attachments_directory	str, None	None	path to the directory where possible attachments will be saved to, if not given then attachment filenames are returned in a list of the return dictionary in the key 'attachments'

Returned dictionary contains:

headers of the email
attachments the filenames of the attachments or if attachments have been saved then they are absolute filepaths to each attachment
body_text is the TEXT formatted content of the email body
body_html is the HTML formatted content of the email body

param eml_filepath:
	filepath to the EML file
param save_attachments_directory:
	path to the directory where possible attachments will be saved to, if not given then attachment filenames are returned in a list of the return dictionary in the key 'attachments'
return:	dictionary containing information aboutthe EML message

Argument	Type	Default value	Description
folder_name	str	None	name for the new folder

param folder_name:
	name for the new folder
return:	True if operation was successful, False if not

Argument	Type	Default value	Description
folder_name	str	None	current folder name

param folder_name:
	current folder name
return:	True if operation was successful, False if not

Delete Message

Delete single message from server based on criterion.

Arguments

Argument	Type	Default value	Description
criterion	str, dict	None	filter messages based on this search, can also be a message dictionary
source_folder	str	None	defaults to already selected folder, but can be set to delete message in a specific folder

param criterion:
	filter messages based on this search, can also be a message dictionary
param source_folder:
	defaults to already selected folder, but can be set to delete message in a specific folder
return:	True if success, False if not

If criterion does not return exactly 1 message then delete is not done.

Examples

Delete Message SUBJECT "Greetings RPA developer"

Argument	Type	Default value	Description
criterion	str, list	None	filter messages based on this search, can also be a list of message dictionaries
limit	int	None	maximum number of message to delete
source_folder	str	None	defaults to already selected folder, but can be set to delete message in a specific folder

param criterion:
	filter messages based on this search, can also be a list of message dictionaries
param limit:	maximum number of message to delete
param source_folder:
	defaults to already selected folder, but can be set to delete message in a specific folder
return:	True if success, False if not

Do Message Actions

Do actions to messages matching criterion and if given, source folder

Arguments

Argument	Type	Default value	Description
criterion	str		perform actions on messages matching this
actions	list	None	list of actions to perform on matching messages
source_folder	str	None	look for messages in this folder, default all folders
target_folder	str	None	can be file path or email folder (for example action: msg_copy)
labels	str	None	comma separated list of labels (for example action: glabel_add)
limit	int	None	maximum number of messages (for example action: msg_delete)
overwrite	bool	False	to control if file should overwrite (for example action: msg_attachment_save)
prefix	str	None	prefix to be added into filename (for example: msg_save)

Actions can be:

msg_copy
msg_delete
msg_flag
msg_unflag
msg_read
msg_unread
msg_save
msg_attachment_save
glabel_add
glabel_remove

Result object contains following attributes:

actions_done, number of messages on which action was performed
message_count, number of messages matching criterion
ids, message ids matching criterion
uids, dictionary of message uids and message content

param criterion:
	perform actions on messages matching this
param actions:	list of actions to perform on matching messages
param source_folder:
	look for messages in this folder, default all folders
param target_folder:
	can be file path or email folder (for example action: msg_copy)
param labels:	comma separated list of labels (for example action: glabel_add)
param limit:	maximum number of messages (for example action: msg_delete)
param overwrite:
	to control if file should overwrite (for example action: msg_attachment_save)
param prefix:	prefix to be added into filename (for example: msg_save)
return:	result object

${actions}= Create List msg_unflag msg_read msg_save msg_attachment_save Do Message Actions SUBJECT "Order confirmation" ... ${actions} ... source_folder=XXX ... target_folder=${CURDIR} ... overwrite=True

Email To Document

Convert a raw e-mail into a Word document.

Arguments

Argument	Type	Default value	Description
input_source	str, Path, BinaryIO, bytes	null	Path, bytes or file-like object with the input raw e-mail content
output_path	str, Path	null	Where to save the output docx file

This keyword extracts the HTML (or Text) content from the passed input e-mail and saves it into docx format at the provided output path.

param input_source:
	Path, bytes or file-like object with the input raw e-mail content
param output_path:
	Where to save the output docx file

Examples

Robot Framework

Convert email to docx ${mail_file} = Get Work Item File mail.eml Email To Document ${mail_file} ${OUTPUT_DIR}${/}mail.docx

Python

from pathlib import Path from RPA.Email.ImapSmtp import ImapSmtp from RPA.Robocorp.WorkItems import WorkItems lib_work = WorkItems() lib_mail = ImapSmtp() def convert_email_to_docx(): lib_work.get_input_work_item() mail_file = lib_work.get_work_item_file("mail.eml") lib_mail.email_to_document(mail_file, Path("./output") / "mail.docx") convert_email_to_docx()

Flag Messages

Mark messages as flagged

Arguments

Argument	Type	Default value	Description
criterion	str, dict	None	mark messages matching criterion
unflag	bool	False	to mark messages as not flagged

param criterion:
	mark messages matching criterion
param unflag:	to mark messages as not flagged
return:	successful operations (int), matching messages (int)

Examples

${flagged} ${oftotal} Flag Messages SUBJECT rpa ${unflagged} ${oftotal} Flag Messages SUBJECT rpa unflag=True

Generate Oauth String

Generate and return an OAuth2 string compatible with the IMAP/POP/SMTP XOAUTH2 protocol.

Arguments

Argument	Type	Default value	Description
username	str	null	The e-mail address you're going to send the e-mail with.
access_token	str	null	Access token string found in the dictionary obtained with Get OAuth Token or Refresh OAuth Token.

This string usually gets passed to the Authorize keyword as password when is_oauth=${True}.

param access_token:
param username:	The e-mail address you're going to send the e-mail with.
	Access token string found in the dictionary obtained with `Get OAuth Token` or `Refresh OAuth Token`.
returns:	Base64 encoded string packing these credentials and replacing the legacy password when enabling the OAuth2 flow.

Example: Robot Framework

*** Tasks *** Authorize ImapSmtp ${password} = Generate OAuth String ${username} ... ${token}[access_token] Authorize account=${username} is_oauth=${True} ... password=${password}

Generate Oauth Url

Generates an authorization URL which must be opened by the user to start the OAuth2 flow and obtain an authorization code as response.

Arguments

Argument	Type	Default value	Description
client_id	str	null	Client app ID. (generated by the provider)

param client_id:
	Client app ID. (generated by the provider)
returns:	Authorization URL string not containing any sensitive info in it.

Example: Robot Framework

*** Tasks *** Start OAuth Flow ${auth_url} = Generate OAuth URL ... client_id=810482312368-19htmcgcj*******googleusercontent.com Log Start OAuth2 flow: ${auth_url}

Get Decoded Email Body

Decodes email body and extracts its text/html content.

Arguments

Argument	Type	Default value	Description
message		null	Raw 7-bit message body input e.g. from imaplib. Double encoded in quoted-printable and latin-1
html_first	bool	False	Prioritize html extraction over text when this is True

Automatically detects character set if the header is not set.

param html_first:
param message:	Raw 7-bit message body input e.g. from imaplib. Double encoded in quoted-printable and latin-1
	Prioritize html extraction over text when this is True
returns:	Message body as unicode string and a boolean telling if the message has attachments

Get Folder List

Get list of folders on the server

Arguments

Argument	Type	Default value	Description
subdirectory	str	None	list subdirectories for this folder
pattern	str	None	list folders matching this pattern

param subdirectory:
	list subdirectories for this folder
param pattern:	list folders matching this pattern
return:	list of folders

Examples

@{folders} Get Folder List @{folders} Get Folder List pattern=important @{folders} Get Folder List subdirectory=sub

Get Oauth Token

Exchanges the code obtained previously with Generate OAuth URL for a token.

Arguments

Argument	Type	Default value	Description
client_secret	str	null	Client app secret. (generated by the provider)
response_url	str	null	The final URL containing the authorization code found in the address bar after authenticating and authorizing the Client app through the authorization URL.

param client_secret:
	Client app secret. (generated by the provider)
param response_url:
	The final URL containing the authorization code found in the address bar after authenticating and authorizing the Client app through the authorization URL.
returns:	A dictionary containing the access & refresh token, plus metadata.

Example: Robot Framework

*** Tasks *** Finish OAuth Flow ${token} = Get OAuth Token ... client_secret=GOCSPX-******mqZAW89 ... response_url=${resp_url} # redirect of Generate OAuth URL

List Messages

Return list of messages matching criterion.

Arguments

Argument	Type	Default value	Description
criterion	str		list emails matching this, defaults to ""
source_folder	str	None	list messages from this folder
readonly	bool	True	set False if you want to mark matching messages as read

param criterion:
	list emails matching this, defaults to ""
param source_folder:
	list messages from this folder
param readonly:	set False if you want to mark matching messages as read
return:	list of messages

Note. listing messages without source_folder might take a long time

Examples

@{emails} List Messages SUBJECT "rpa task" FOR ${email} IN @{EMAILS} Log ${email}[Subject] Log ${email}[From] Log ${email}[Date] Log ${email}[Delivered-To] Log ${email}[Received] Log ${email}[Has-Attachments] Log ${email}[uid] END

Mark As Read

Mark messages as read

Arguments

Argument	Type	Default value	Description
criterion	str, dict	None	mark messages matching criterion
unread	bool	False	to mark messages as not read

param criterion:
	mark messages matching criterion
param unread:	to mark messages as not read
return:	successful operations (int), matching messages (int)

Examples

${read} ${oftotal} Mark As Read SUBJECT rpa

Mark As Unread

Mark messages as not read

Arguments

Argument	Type	Default value	Description
criterion	str, dict	None	mark messages matching criterion

param criterion:
	mark messages matching criterion
return:	successful operations (int), matching messages (int)

Examples

${unread} ${oftotal} Mark As Unread SUBJECT rpa

Move Messages

Move messages from source folder to target folder

Arguments

Argument	Type	Default value	Description
criterion	str, dict	None	move messages matching criterion
target_folder	str	None	where messages should be move into
source_folder	str	None	location of the messages, default INBOX

param criterion:
	move messages matching criterion
param source_folder:
	location of the messages, default INBOX
param target_folder:
	where messages should be move into
return:	True if all move operations succeeded, False if not

Examples

${result}= Move Messages ... criterion=SUBJECT "order confirmation 32" ... target_folder=yyy ${result}= Move Messages ... criterion=ALL ... source_folder=yyy ... target_folder=XXX

Move Messages By Ids

Move message by their Message-ID's from source folder to target folder

Arguments

Argument	Type	Default value	Description
message_ids	str, List	null	one Message-ID as string or list of Message-IDs
target_folder	str	null	where messages should be move into
source_folder	str	null	location of the messages, default INBOX
use_gmail_search	bool	False	set to True to use Rfc822msgid search, default is HEADER Message-ID search

param message_ids:
	one Message-ID as string or list of Message-IDs
param source_folder:
	location of the messages, default INBOX
param target_folder:
	where messages should be move into
param use_gmail_search:
	set to True to use Rfc822msgid search, default is HEADER Message-ID search
return:	True if all move operations succeeded, False if not

Refresh Oauth Token

Refreshes the token as the access one usually expires after 1h and the refresh one never expires. (as long as it doesn't get revoked)

Arguments

Argument	Type	Default value	Description
client_id	str	null	Client app ID. (generated by the provider)
client_secret	str	null	Client app secret. (generated by the provider)
token	dict	null	Full token dictionary previously obtained with Get OAuth Token.

param client_id:
	Client app ID. (generated by the provider)
param client_secret:
	Client app secret. (generated by the provider)
param token:	Full token dictionary previously obtained with `Get OAuth Token`.
returns:	A token dictionary containing a new access token and updated metadata.

Example: Robot Framework

*** Tasks *** Refresh OAuth Flow ${token} = Refresh OAuth Token ... client_id=810482312368-19htmcgcj*******googleusercontent.com ... client_secret=GOCSPX-******mqZAW89 ... token=${token} # from Get OAuth Token

Remove Gmail Labels

Remove GMail labels to messages matching criterion and if given, source folder

Arguments

Argument	Type	Default value	Description
labels		null	comma separated list of labels to remove
criterion		null	unlabel messages matching criterion
source_folder	str	None	look for messages in this folder, default all folders

param criterion:
param labels:	comma separated list of labels to remove
	unlabel messages matching criterion
param source_folder:
	look for messages in this folder, default all folders
return:	status of the operation

Examples

Remove Gmail Labels wip SUBJECT "order confirmation" Remove Gmail Labels wip SUBJECT "order confirmation" customerfolder

Rename Folder

Rename email folder

Arguments

Argument	Type	Default value	Description
oldname	str	None	current folder name
newname	str	None	new name for the folder
suppress_error	bool	False	to silence warning message, defaults to False

param suppress_error:
param oldname:	current folder name
param newname:	new name for the folder
	to silence warning message, defaults to False
return:	True if operation was successful, False if not

Examples

Rename Folder subfolder filtered

Save Attachment

Save mail attachment of a single given email on the local disk.

Arguments

Argument	Type	Default value	Description
message	dict, Message	null	message item
target_folder	str, None	null	local folder for saving attachments to (needs to exist), defaults to user's home directory if None
overwrite	bool	null	overwrite existing file if True, defaults to False
prefix	str, None	None	optional filename prefix added to the attachments, empty by default

param target_folder:
param message:	message item
	local folder for saving attachments to (needs to exist), defaults to user's home directory if None
param overwrite:
	overwrite existing file if True, defaults to False
param prefix:	optional filename prefix added to the attachments, empty by default
return:	list of saved attachments (list of absolute filepaths) in one email

Examples

@{emails} = List Messages ALL FOR ${email} IN @{emails} IF ${email}[Has-Attachments] Log To Console Saving attachment for: ${email}[Subject] ${attachments} = Save Attachment ... ${email} ... target_folder=${CURDIR} ... overwrite=${True} Log To Console Saved attachments: ${attachments} END END

Save Attachments

Save mail attachments of emails matching criterion on the local disk.

Arguments

Argument	Type	Default value	Description
criterion	str		attachments are saved for mails matching this, defaults to ""
target_folder	str, None	None	local folder for saving attachments to (needs to exist), defaults to user's home directory if None
overwrite	bool	False	overwrite existing file if True, defaults to False
prefix	str, None	None	optional filename prefix added to the attachments, empty by default

param criterion:
	attachments are saved for mails matching this, defaults to ""
param target_folder:
	local folder for saving attachments to (needs to exist), defaults to user's home directory if None
param overwrite:
	overwrite existing file if True, defaults to False
param prefix:	optional filename prefix added to the attachments, empty by default
return:	list of saved attachments (absolute file paths) of all emails

Examples

${attachments} = Save Attachments SUBJECT "rpa task" ... target_folder=${CURDIR}${/}messages overwrite=${True} FOR ${file} IN @{attachments} OperatingSystem.File Should Exist ${file} END

Save Messages

Save messages based on criteria and store them to target folder with attachment files.

Arguments

Argument	Type	Default value	Description
criterion	str, dict, list, None	None	filter messages based on this, defaults to ""
target_folder	str, None	None	path to folder where message are saved, defaults to None
prefix	str, None	None	optional filename prefix added to the attachments, empty by default

Does not save message if target_folder is not given.

param criterion:
	filter messages based on this, defaults to ""
param target_folder:
	path to folder where message are saved, defaults to None
param prefix:	optional filename prefix added to the attachments, empty by default
return:	True if succeeded, False otherwise

Examples

Save Messages SUBJECT Important message target_folder=${USERDIR}${/}messages

Select Folder

Select folder by name

Arguments

Argument	Type	Default value	Description
folder_name	str	INBOX	name of the folder to select
readonly	bool	False	if set to True then message flags are not modified

param folder_name:
	name of the folder to select
param readonly:	if set to True then message flags are not modified
return:	message count in the selected folder

Returns number of messages in the folder or exception if folder does not exist on the server.

Examples

Select Folder subfolder

Send Message

Send SMTP email

Arguments

Argument	Type	Default value	Description
sender	str	null	who is sending, ie. 'from'
recipients	List[str], str, None	None	who is receiving, ie. 'to'
subject	str		mail subject field
body	str		mail body content
attachments	List[str], str, None	None	list of filepaths to attach
html	bool	False	if message content is in HTML, default False
images	List[str], str, None	None	list of filepaths for inline images
cc	List[str], str, None	None	list of email addresses for email 'cc' field
bcc	List[str], str, None	None	list of email addresses for email 'bcc' field
attachment_position	AttachmentPosition, None	TOP	content position for attachment, default top
in_reply_to	str, None	None	the 'Message ID' to which this message is in reply to, for example
return_path	str, None	None	email address which should receive "bounce messages"

param recipients:
param sender:	who is sending, ie. 'from'
	who is receiving, ie. 'to'
param subject:	mail subject field
param body:	mail body content
param attachments:
	list of filepaths to attach
param html:	if message content is in HTML, default False
param images:	list of filepaths for inline images
param cc:	list of email addresses for email 'cc' field
param bcc:	list of email addresses for email 'bcc' field
param attachment_position:
	content position for attachment, default top
param in_reply_to:
	the 'Message ID' to which this message is in reply to, for example <message_id_for_reply_to>
param return_path:
	email address which should receive "bounce messages"

Valid sender values

First Lastname <address@domain>
address@domain

About in_reply_to

In addition of setting in_reply_to parameter to match the 'Message ID' of the email this message is replying to, some email servers require that also subject of the original email is included in the reply email subject with re: prefix, ie. "re: Why it is best to use Robocorp RPA" or with the original email subject.

System Message: WARNING/2 (<string>, line 24); backlink

Inline interpreted text or phrase reference start-string without end-string.

And please note that in_reply_to the 'Message ID' needs to contain < in the start of the ID and > at the end of the ID.

About return_path

Email servers tend to set 'Return-Path' of the email on their own so in some cases user given address won't work as the email server does not use the user set address. If possible, the email server's configuration can be changed to ensure that 'Return-Path' header is respected.

Examples

Send Message sender@domain.com recipient@domain.com ... cc=need_to_know@domain.com ... bcc=hidden_copy@domain.com ... subject=Greetings Software Robot Developer ... body=${email_body} ... attachments=${CURDIR}${/}report.pdf # Fixing attachments to the bottom of the content Send Message sender@domain.com recipient@domain.com ... subject=Greetings Software Robot Developer ... body=${email_body} ... attachments=${CURDIR}${/}report.pdf ... attachment_position=bottom

Argument	Type	Default value	Description
account	str, None	None	user account as string, defaults to None
password	str, None	None	user password as string, defaults to None

param account:	user account as string, defaults to None
param password:	user password as string, defaults to None

Argument	Type	Default value	Description
criterion	str, dict	None	mark messages matching criterion

param criterion:
	mark messages matching criterion
return:	successful operations (int), matching messages (int)

Argument	Type	Default value	Description
criterion	str		message filter to wait for, defaults to ""
timeout	float	5.0	total time in seconds to wait for email, defaults to 5.0
interval	float	1.0	time in seconds for new check, defaults to 1.0
readonly	bool	True	set False if you want to mark matching messages as read

param criterion:
	message filter to wait for, defaults to ""
param timeout:	total time in seconds to wait for email, defaults to 5.0
param interval:	time in seconds for new check, defaults to 1.0
param readonly:	set False if you want to mark matching messages as read
return:	list of messages

Examples

@{emails} Wait For Message SUBJECT "rpa task" timeout=300 interval=10