RPA.Email.ImapSmtp
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 labels: | comma separated list of labels to add |
---|---|
param criterion: | |
label messages matching criterion | |
param source_folder: | |
look for messages in this folder, default all folders | |
return: | status of the operation |
Examples
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 account: | user account as string, defaults to None |
---|---|
param password: | user password as string, defaults to None |
param smtp_server: | |
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 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 account: | IMAP account name, defaults to None |
---|---|
param password: | IMAP account password, defaults to None |
param imap_server: | |
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 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 account: | SMTP account name, defaults to None |
---|---|
param password: | SMTP account password, defaults to None |
param smtp_server: | |
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
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 |
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 messages from server based on criterion.
Arguments
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 |
Examples
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 |
Examples
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
Python
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
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 username: | The e-mail address you're going to send the e-mail with. |
---|---|
param access_token: | |
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
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
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 message: | Raw 7-bit message body input e.g. from imaplib. Double encoded in quoted-printable and latin-1 |
---|---|
param html_first: | |
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 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
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
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
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
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
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 |
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
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 labels: | comma separated list of labels to remove |
---|---|
param criterion: | |
unlabel messages matching criterion | |
param source_folder: | |
look for messages in this folder, default all folders | |
return: | status of the operation |
Examples
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 oldname: | current folder name |
---|---|
param newname: | new name for the folder |
param suppress_error: | |
to silence warning message, defaults to False | |
return: | True if operation was successful, False if not |
Examples
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 message: | message item |
---|---|
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 (list of absolute filepaths) in one email |
Examples
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
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
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
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 sender: | who is sending, ie. 'from' |
---|---|
param recipients: | |
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.
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 hello message to SMTP server.
Required step when creating SMTP connection.
Set credentials
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 |
param account: | user account as string, defaults to None |
---|---|
param password: | user password as string, defaults to None |
Examples
Wait for email matching criterion to arrive into mailbox.
Arguments
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 |