- Publicity: Public Only All
email-inbound-procs.tcl
Provides API for importing email under a variety of deployment conditions.
- Location:
- packages/acs-mail-lite/tcl/email-inbound-procs.tcl
- Created:
- 19 Jul 2017
- CVS Identification:
$Id: email-inbound-procs.tcl,v 1.15.2.17 2023/07/10 09:16:39 gustafn Exp $
Procedures in this file
- acs_mail_lite::bounce_address (private)
- acs_mail_lite::bounce_ministry (private)
- acs_mail_lite::bounce_prefix (private)
- acs_mail_lite::bouncing_user_p (private)
- acs_mail_lite::check_bounces (private)
- acs_mail_lite::email_type (public)
- acs_mail_lite::inbound_cache_clear (private)
- acs_mail_lite::inbound_cache_hit_p (private)
- acs_mail_lite::inbound_email_context (private)
- acs_mail_lite::inbound_filters (private)
- acs_mail_lite::inbound_prioritize (public)
- acs_mail_lite::inbound_queue_insert (private)
- acs_mail_lite::inbound_queue_pull (private)
- acs_mail_lite::inbound_queue_pull_one (private)
- acs_mail_lite::inbound_queue_release (private)
- acs_mail_lite::sched_parameters (public)
- acs_mail_lite::section_id_of (private)
- acs_mail_lite::section_ref_of (private)
- acs_mail_lite::unique_id_create (private)
- acs_mail_lite::unique_id_parse (private)
Detailed information
acs_mail_lite::bounce_address (private)
acs_mail_lite::bounce_address -user_id user_id -package_id package_id \ -message_id message_id
Composes a bounce address. If parameter FixedSenderEmail empty, message_id is used. If message_id is empty, the legacy approach for creating bounce_address is used.
- Switches:
- Options:
- -user_id (required)
- -package_id (required)
- -message_id (required)
- -user_id
- user_id of the mail recipient
- -package_id
- package_id of the mail sending package (needed to call package-specific code to deal with bounces)
- -message_id
- message-id of the mail
- Returns:
- bounce address
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::bounce_ministry (private)
acs_mail_lite::bounce_ministry -header_array_name header_array_name
Check if this email is notifying original email bounced. If is a bounced notification, process it. Returns 1 if bounced or an auto generated reply that should be ignored, otherwise returns 0 Expects header_array to have been previously processed by these procs:
- Switches:
- -header_array_name (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::bounce_prefix (private)
acs_mail_lite::bounce_prefix
- Returns:
- bounce prefix for x-envelope-from
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::bouncing_user_p (private)
acs_mail_lite::bouncing_user_p -user_id user_id
Checks if email address of user is bouncing mail
- Switches:
- Options:
- -user_id (required)
- -user_id
- user to be checked for bouncing
- Returns:
- boolean 1 if bouncing 0 if ok.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::check_bounces (private)
acs_mail_lite::check_bounces
Daily proc that sends out warning mail that emails are bouncing and disables emails if necessary
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::email_type (public)
acs_mail_lite::email_type [ -subject subject ] [ -from from ] \ [ -headers headers ] [ -header_arr_name header_arr_name ] \ [ -reply_too_fast_s reply_too_fast_s ] \ [ -check_subject_p check_subject_p ]
Scans email's subject, from and headers for actionable type.
Returns actionable type and saves same type in header_arr_name(aml_type), and saves some normalized header info to reduce redundant processing downstream. See code comments for details.
Actional types: 'auto_gen' 'auto_reply', 'bounce', 'in_reply_to' or empty string indicating 'other' type.
Adds these index to headers array:
- 'auto_reply' may be a Delivery Status Notification for example.
- 'bounce' is a specific kind of Delivery Status Notification.
- 'in_reply_to' is an email reporting to originate from local email, which needs to be tested further to see if OpenACS needs to act on it versus a reply to a system administrator email for example.
- 'auto_gen' is an auto-generated email that does not qualify as 'auto_reply', 'bounce', or 'in_reply_to'
- '' (Empty string) refers to email that the system does not recognize as a reply of any kind. If not a qualifying type, returns empty string.
- received_cs: the received time of email in tcl clock epoch time.
- aml_type: the same value returned by this proc.
If additional headers not calculated, they have value of empty string.
If headers and header_arr_name provided, only header_arr_name will be used, if header_arr_name contains at least one value.
If check_subject_p is set 1, checks for common subjects identifying autoreplies. This is not recommended to rely on exclusively. This feature provides a framework for extending classification of emails for deployment routing purposes.
If array includes keys from 'ns_imap struct', such as internaldate.*, then adds header with epoch time quivilent to header index received_cs
- Switches:
- -subject (optional)
- of email
- -from (optional)
- of email
- -headers (optional)
- of email, a block of text containing all headers and values
- -header_arr_name (optional)
- -reply_too_fast_s (optional, defaults to
"10"
)- -check_subject_p (optional, defaults to
"0"
)- Set to 1 to check email subject.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::inbound_cache_clear (private)
acs_mail_lite::inbound_cache_clear
Clears table of all email uids for all history. All unread input emails will be considered new and reprocessed. To keep history, just temporarily forget it instead (delete it from acs_mail_lite_email_uid_id_map).
If you are not sure if this will do what you want, try setting reprocess_old_p to '1'.
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_cache_hit_p (private)
acs_mail_lite::inbound_cache_hit_p email_uid uidvalidity \ mailbox_host_name
Check email unique id (UID) against history in table. If already exists, returns 1 otherwise 0. Adds checked case to cache if not already there. uidvalidity is defined by imap RFC 3501 2.3.1.1 https://tools.ietf.org/html/rfc3501#section-2.3.1.1 Other protocols have an analog mechanism, or one can be made locally to be equivalent in use.
- Parameters:
- email_uid (required)
- uidvalidity (required)
- mailbox_host_name (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_email_context (private)
acs_mail_lite::inbound_email_context \ [ -header_array_name header_array_name ] \ [ -header_name_list header_name_list ]
Returns openacs data associated with original outbound email in the header_array_name and as an ordered list of values: package_id, party_id, object_id, other, datetime_cs datetime_cs is the time in seconds since Tcl epoch. other can be most any data represented in SQL text. By accessing all email headers, various scenarios of OpenACS sender and replies can be checked to increase likelihood of retrieving data in context of email. Array indexes have suffix aml_ added to index name: aml_package_id, aml_party_id, aml_object_id, aml_other, aml_datetime_cs If a value is not found, an empty string is returned for the value.
- Switches:
- -header_array_name (optional)
- -header_name_list (optional)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_filters (private)
acs_mail_lite::inbound_filters [ -headers_arr_name headers_arr_name ]
Flags to ignore an inbound email that does not pass filters. Returns 1 if email should be ignored, otherwise returns 0. Headers and values are not alphanumeric case sensitive. Inbound filters are dynamically updated via acs_mail_lite::sched_parameters. Instead of rejecting, an email can be filtered to low priority by using acs_mail_lite::inbound_prioritize parameters
- Switches:
- -headers_arr_name (optional)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_prioritize (public)
acs_mail_lite::inbound_prioritize \ [ -header_array_name header_array_name ] \ [ -size_chars size_chars ] [ -received_cs received_cs ] \ [ -subject subject ] [ -package_id package_id ] \ [ -party_id party_id ] [ -object_id object_id ]
Returns a prioritization integer for assigning priority to an inbound email. Another proc processes in order of lowest number first. Returns empty string if input values from email are not expected types. Priority has 3 categories: high priority, normal priority, low priority as specified in acs_mail_lite::sched_parameters Expects parameters to be passed within an array, or individually. When passing via an array, parameter names have suffix "aml_". For example, size_chars becomes aml_size_chars. Array values take precedence, if they exist.
- Switches:
- -header_array_name (optional)
- -size_chars (optional)
- of email
- -received_cs (optional)
- seconds since epoch when email received
- -subject (optional)
- of email
- -package_id (optional)
- associated with email (if any)
- -party_id (optional)
- associated with email (if any)
- -object_id (optional)
- associated with email (if any)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::inbound_queue_insert (private)
acs_mail_lite::inbound_queue_insert \ [ -headers_arr_name headers_arr_name ] \ [ -parts_arr_name parts_arr_name ] [ -priority priority ] \ [ -aml_email_id aml_email_id ] [ -section_ref section_ref ] \ [ -struct_list struct_list ] [ -error_p error_p ]
Adds a new, actionable incoming email to the queue for prioritized processing. Returns aml_email_id if successful, otherwise empty string.
- Switches:
- -headers_arr_name (optional)
- -parts_arr_name (optional)
- -priority (optional)
- -aml_email_id (optional)
- -section_ref (optional)
- -struct_list (optional)
- -error_p (optional, defaults to
"0"
)- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_queue_pull (private)
acs_mail_lite::inbound_queue_pull
Identifies and processes highest priority inbound email.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_queue_pull_one (private)
acs_mail_lite::inbound_queue_pull_one -h_array_name h_array_name \ -p_array_name p_array_name -aml_email_id aml_email_id \ [ -mark_processed_p mark_processed_p ] \ [ -legacy_array_name legacy_array_name ]
Puts email referenced by aml_email_id from the inbound queue into array of h_array_name and p_array_name for use by registered callbacks. Arrays are repopulated with values in the same manner that acs_mail_lite::inbounde_queue_insert receives them. See below for details. When complete, marks the email in the queue as processed, if mark_processed_p is 1. Array content corresponds to these tables:
h_arr($name) $value acs_mail_lite_ie_headers Some indexes match fields of table acs_mail_lite_from_external: h_arr(aml_email_id) assigned by acs_mail_lite::inbound_queue_insert h_arr(aml_to) to email including any label h_arr(aml_to_addrs) to_email_addrs h_arr(aml_from) from email including any label h_arr(aml_from_addrs) from_email_addrs h_arr(aml_priority) priority h_arr(aml_subject) email subject (normalized index reference). h_arr(aml_msg_id) email message-id or msg-id's cross-reference see acs_mail_lite_msg_id_map.msg_id h_arr(aml_size_chars) size_chars Some headers are transferred from the email generation process. See acs_mail_lite::unique_id_create for details: h_arr(aml_package_id) h_arr(aml_party_id) h_arr(aml_object_id) h_arr(aml_other) Some headers are internally generated during input: h_arr(aml_type) Type of email from acs_mail_lite::email_type h_arr(aml_received_cs) Time received in seconds since Tcl epoch h_arr(aml_datetime_cs) Time unique_id generated in seconds since Tcl epoch h_arr(aml_processed_p) processed_p h_arr(aml_priority) a priority number assigned to email. Email parts (of body) are kept in a separate array: p_arr($section_ref,<field>) acs_mail_lite_ie_parts (content of a part) p_arr($section_ref,nv_list) acs_mail_lite_part_nv_pairs p_arr(section_ref_list) list of section_refs where index is section_ref based on section_ref, and where top most section_ref is a natural number as there may be more than one tree. Specifically, for p_arr array: content is p_arr($section_ref,content) c_type is p_arr($section_ref,c_type) filename is p_arr($section_ref,filename) c_filepathname is p_arr($section_ref,c_filepathname) where: c_type is content-type header filename is filename of an attachment in email c_filepathname is the filepathname within the system. Each section may have headers: To avoid any header-name collision with content, c_type etc, headers are supplied in a name_value_list only: list of headers by section is p_arr($section_ref,name_value_list) list of section_refs is p_arr(section_ref_list) For direct compatibility with legacy email systems that used:acs_mail_lite::email_parse, a compatible array is passed to legacy_array_name, if parameter is used.
- Switches:
- -h_array_name (required)
- -p_array_name (required)
- -aml_email_id (required)
- -mark_processed_p (optional, defaults to
"1"
)- -legacy_array_name (optional)
- See Also:
- acs_mail_lite::email_parse
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::inbound_queue_release (private)
acs_mail_lite::inbound_queue_release
Delete email from queue that have been flagged 'release'. This does not affect email via imap or other connections.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
acs_mail_lite::sched_parameters (public)
acs_mail_lite::sched_parameters [ -sredpcs_override sredpcs_override ] \ [ -reprocess_old_p reprocess_old_p ] \ [ -max_concurrent max_concurrent ] \ [ -max_blob_chars max_blob_chars ] [ -mpri_min mpri_min ] \ [ -mpri_max mpri_max ] [ -hpri_package_ids hpri_package_ids ] \ [ -lpri_package_ids lpri_package_ids ] \ [ -hpri_party_ids hpri_party_ids ] \ [ -lpri_party_ids lpri_party_ids ] \ [ -hpri_subject_glob hpri_subject_glob ] \ [ -lpri_subject_glob lpri_subject_glob ] \ [ -hpri_object_ids hpri_object_ids ] \ [ -lpri_object_ids lpri_object_ids ] \ [ -reject_on_hit reject_on_hit ] \ [ -reject_on_miss reject_on_miss ]
Returns a name value list of parameters used by ACS Mail Lite scheduled procs. If a parameter is passed with value, the value is assigned to parameter.
- Switches:
- Options:
- -sredpcs_override (optional)
- If set, use this instead of si_dur_per_cycle_s. See www/doc/analysis-notes
- -reprocess_old_p (optional)
- If set, does not ignore prior unread email
- -max_concurrent (optional)
- Max concurrent processes to import (fast priority)
- -max_blob_chars (optional)
- Email body parts larger are stored in a file.
- -mpri_min (optional)
- Minimum threshold integer for medium priority. Smaller is fast High priority.
- -mpri_max (optional)
- Maximum integer for medium priority. Larger is Low priority.
- -hpri_package_ids (optional)
- List of package_ids to process at fast priority.
- -lpri_package_ids (optional)
- List of package_ids to process at low priority.
- -hpri_party_ids (optional)
- List of party_ids to process at fast/high priority.
- -lpri_party_ids (optional)
- List of party_ids to process at low priority.
- -hpri_subject_glob (optional)
- When email subject matches, flag as fast priority.
- -lpri_subject_glob (optional)
- When email subject matches, flag as low priority.
- -hpri_object_ids (optional)
- List of object_ids to process at fast/high priority.
- -lpri_object_ids (optional)
- List of object_ids to process at low priority.
- -reject_on_hit (optional)
- Name/Value list. See acs_mail_lite::inbound_filters
- -reject_on_miss (optional)
- Name/Value list. See acs_mail_lite::inbound_filters
- -sched_parameter
- value
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::section_id_of (private)
acs_mail_lite::section_id_of section_ref
Returns section_id representing a section_ref. Section_ref has format of counting numbers separated by dot. Section_id is an integer. First used here by ns_imap body and adopted for general email part refs.
- Parameters:
- section_ref (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::section_ref_of (private)
acs_mail_lite::section_ref_of section_id
Returns section_ref represented by section_id. Section_id is an integer. Section_ref has format of counting numbers separated by dot. First used here by ns_imap body and adopted for general email part refs. Defaults to empty string (top level reference and a log warning) if not found.
- Parameters:
- section_id (required)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::unique_id_create (private)
acs_mail_lite::unique_id_create [ -unique_id unique_id ] \ [ -package_id package_id ] [ -party_id party_id ] \ [ -object_id object_id ] [ -other other ]
Returns a unique_id for an outbound email header message-id. Signs unique_id when package_id, party_id, object_id, and/or other info are supplied. party_id is not supplied if its value is empty string or 0. package_id not supplied when it is the default acs-mail-lite package_id. If unique_id is empty string, creates a unique_id then processes it.
- Switches:
- -unique_id (optional)
- -package_id (optional)
- -party_id (optional)
- -object_id (optional)
- -other (optional)
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check
acs_mail_lite::unique_id_parse (private)
acs_mail_lite::unique_id_parse -message_id message_id
Parses a message-id compatible reference created by acs_mail_lite::unique_id_create. Returns package_id, party_id, object_id, other, datetime_cs in a name value list. datetime_cs is approximate system time in seconds from epoch when header was created.
- Switches:
- -message_id (required)
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- acs_mail_lite_inbound_procs_check