Sympa::List(3Sympa)

📦
version 6.2.80 · 14 versions
, in fedora 43, fedora 44

✨ Sympa::List(3Sympa) ✨ — the mailing list page, but make it cute

okay so bestie, gather round, because this is the manual page for Sympa::List from sympa 6.2.80, and it's literally the whole entire vibe of what a mailing list is inside Sympa. no cap. 💅

🌸 NAME 🌸

Sympa::List — Mailing list. that's it, that's the name, she's simple, she's iconic, she's a mailing list. 👑

🦋 DESCRIPTION 🦋

so Sympa::List represents the mailing list on Sympa. like, that's the whole job. she's the object that is the list. periodt.

✨ Methods ✨

💖 new( $name, [ $domain [ {options...} ] ] )

Constructor. she creates a brand new object that's gonna be used for a list, and eventually (iykyk) loads the list if a name is given. returns a List object. slay.

Parameters

FIXME @todo doc — yeah bestie they left this one blank, we're all just vibing with the mystery here. 🙈

💖 add_list_admin ( $role, $user, ..., [ replace => 1 ], [ stash => $arrayref ] )

Instance method. adds new admin user(s) to the list. If replace => 1 is specified, may overwrite existing entries. TBD. (we love an unfinished thought, honestly.) 🎀

💖 add_list_header ( $message, $field_type )

FIXME @todo doc — again, blank, we move. 🦋

💖 add_list_member ( $user, ..., [ stash => $arrayref ] )

Instance method. adds new user(s) to the list. TBD.

💖 available_reception_mode ( )

Instance method. FIXME @todo doc

Note: Since Sympa 6.1.18, this returns an array under array context. yes bestie, array context, she's giving scalar-vs-list energy. 🔥

💖 delete_list_admin ( $role, \@emails, [ stash => \@stash ] )

Delete the indicated admin user with the predefined role from the list. $role may be 'owner' or 'editor'. bye bestie, you're out. 👋

💖 delete_list_member ( \@emails, [ exclude => 1 ], [ operation => $operation ], [ stash => \@stash ] )

Delete the indicated users from the list.

Options:

  • \@emails — The emails to be deleted.
  • exclude => 1 — TBD.
  • operation => $operation — Case of deleting: 'auto_del' (bounce management), 'signoff' (manual signoff) or 'del' (deleted by admin).
  • stash => \@stash — TBD.

💖 delete_list_member_picture ( $email )

Deletes a member's picture file. poof. gone. no more pic. 📸

💖 destroy_multiton ( )

Instance method. Destroy multiton instance. FIXME — okay she's a little chaotic but we support her.

💖 dump_users ( ROLE )

Dump user information in user store into file $role.dump under list directory. ROLE may be 'member', 'owner' or 'editor'. we love a data dump bestie. 💾

💖 find_picture_filenames ( $email )

Returns the type of a pictures according to the user. (yes, "a pictures", we didn't write it, we're just reporting it, iconic grammar moment. 💀)

💖 find_picture_paths ( )

Instance method. FIXME @todo doc

💖 find_picture_url ( $email )

Find pictures URL. she's hunting for the URL bestie. 🔍

💖 get_admins ( $role, [ filter => \@filters ] )

Instance method. Gets users of the list with one of following roles.

  • "actual_editor" — Editors belonging to the list. If there are no such users, owners of the list.
  • "editor" — Editors belonging to the list.
  • "owner" — Owners of the list.
  • "privileged_owner" — Owners whose "profile" attribute is "privileged".
  • "receptive_editor" — Editors belonging to the list and whose reception mode is "mail". If there are no such users, owners whose reception mode is "mail".
  • "receptive_owner" — Owners whose reception mode is "mail".

Optional filter may be:

  • [email => $email] — Limit result to the user with their e-mail $email.

Returns:

In array context, returns (possibly empty or single-item) array of users. In scalar context, returns reference to it. In case of database error, returns empty array or undefined value. 😭 (db errors rly do be like that.)

💖 get_admins_email ( $role )

Instance method. Gets an array of emails of list admins with role "receptive_editor", "actual_editor", "receptive_owner" or "owner". the whole roster, bestie. 📧

💖 get_archive_dir ( )

Instance method. FIXME @todo doc

💖 get_available_msg_topic ( )

Instance method. FIXME @todo doc

💖 get_bounce_address ( WHO, [ OPTS, ... ] )

Return the VERP address of the list for the user WHO. bounce bounce bounce. 🏀

FIXME: VERP addresses have the name of originating robot, not mail host. noted, bestie, noted.

💖 get_bounce_dir ( )

Instance method. FIXME @todo doc

💖 get_cert ( )

Instance method. FIXME @todo doc

💖 get_config_changes ( )

Instance method. FIXME @todo doc

Returns the cookie for a list, if available. if not available, no cookie for you. 🍪

💖 get_current_admins ( ... )

Instance method. FIXME @todo doc

💖 get_default_user_options ()

Returns a default option of the list for subscription. the default default, we love a baseline. ✨

💖 get_first_list_member ()

Returns a hash to the first user on the list. first in line bestie, main character energy. 🌟

💖 get_id ( )

Return the list ID, different from the list address (uses the robot name). she's not like other girls (literally, she uses the robot name). 💅

💖 get_including_lists ( $role )

Instance method. List of lists including specified list and hosted by a whole site. lists within lists, it's giving inception fr fr. 🌀

Parameter:

  • $role — Role of included users. 'member', 'owner' or 'editor'.

Returns:

Arrayref of <Sympa::List> instances. Return "undef" on failure. 😔

💖 get_list_member ( USER )

Returns a subscriber of the list. one subscriber, hand-picked. 🫶

💖 get_max_size ()

Returns the maximum allowed size for a message. big messages need not apply. 📏

💖 get_members ( $role, [ offset => $offset ], [ order => $order ], [ limit => $limit ] )

Instance method. Gets users of the list with one of following roles.

  • "member" — Members of the list, either subscribed or included.
  • "unconcealed_member" — Members whose "visibility" property is not "conceal".

Optional parameters:

  • limit => $limit
  • offset => $offset
  • order => $order — TBD.

Returns:

In array context, returns (possibly empty or single-item) array of users. In scalar context, returns reference to it. In case of database error, returns empty array or undefined value. same deal as before bestie, we've been here. 💖

💖 get_msg_count ( )

Instance method. Returns the number of messages sent to the list. FIXME

💖 get_first_bouncing_list_member ( )

Instance method. Get first bouncing user. FIXME

💖 get_next_bouncing_list_member ( )

Instance method. Loop for all subsequent bouncing users. FIXME — she's looping bestie, let her loop. 🔁

💖 get_next_delivery_date ( )

Instance method. Returns the date epoch for next delivery planned for a list.

Note: As of 6.2a.41, returns "undef" if parameter is not set or invalid. Previously it returned current time. so if you're on old Sympa and confused, that's why, bestie. ⏰

💖 get_next_list_member ()

Returns a hash to the next users, until we reach the end of the list. keep going keep going keep going, until we hit the end. 🏃‍♀️

💖 get_param_value ( $param, [ $as_arrayref ] )

instance method. Returns the list parameter value. the parameter is simple (name) or composed (name"."minor) the value is a scalar or a ref on an array of scalar (for parameter digest : only for days). lowkey a mouthful but she's precise, respect. 🎀

💖 get_picture_path ( )

Instance method. FIXME

💖 get_recipients_per_mode ( )

Instance method. FIXME @todo doc

💖 get_reply_to ()

Returns an array with the Reply-To values. reply to whom bestie?? the array knows. 📬

💖 get_resembling_members ( $role, $searchkey )

instance method. TBD.

💖 get_stats ( )

Returns array of the statistics. numbers, so many numbers, we love data. 📊

💖 get_total ( [ 'nocache' ] )

Returns the number of subscribers to the list. and if you pass that 'nocache' bestie, she's going straight to the source, no caching, no shortcuts. 🔥

💖 get_total_bouncing ( )

Instance method. Gets total number of bouncing subscribers.

💖 has_data_sources ( )

Instance method. Checks if a list has data sources.

💖 has_included_users ( $role )

Instance method. FIXME @todo doc

💖 insert_delete_exclusion ( $email, "insert"|"delete" )

Instance method. Update the exclusion table. FIXME @todo doc

💖 is_admin ( $role, $user )

Instance method. Returns true if $user has $role ("privileged_owner", "owner", "actual_editor" or "editor") on the list. are you on the admin squad bestie? 👑

💖 is_archived ()

Returns true is the list is configured to keep archives of its messages. (yes it says "is", the manpage is quirky, we stan.) 🗄️

💖 is_archiving_enabled ( )

Returns true is the list is configured to keep archives of its messages, i.e. process_archive parameter is set to "on". same quirk, same love.

💖 is_available_msg_topic ( $topic )

Instance method. Checks for a topic if it is available in the list (look for each list parameter "msg_topic.name").

💖 is_available_reception_mode ( $mode )

Instance method. Is a reception mode in the parameter reception of the available_user_options section? 🦋

💖 is_subscription_allowed ( )

Instance method. Is it allowed to add or remove subscribers of the list? Added on Sympa 6.2.67b.1. new-ish queen. ✨

💖 is_digest ( )

Instance method. Does the list support digest mode?

💖 is_included ( )

Returns true value if the list is included in another list(s). she's a guest star in someone else's list. 🌟

💖 is_list_member ( USER )

Returns true if the indicated user is member of the list.

💖 is_moderated ()

Returns true if the list is moderated. FIXME this may not be useful. (bestie even the docs are like "idk"] 😭)

💖 is_msg_topic_tagging_required ( )

Instance method. Checks for the list parameter msg_topic_tagging if it is set to 'required'. no tag, no post, rules are rules. 🎀

💖 is_there_msg_topic ( )

Instance method. Tests if some msg_topic are defined.

💖 is_web_archived ( )

Instance method. Is the list web archived?

FIXME: Broken. Use scenario or is_archiving_enabled(). bestie she's broken, do NOT use her, we said what we said. 💀

💖 load ( )

Loads the indicated list into the object. loading... loading... okay she's loaded. 🔄

💖 load_data_sources_list ( $robot )

Instance method. Loads all data sources. FIXME: Used only in wwsympa.fcgi.

💖 may_edit ( $param, $who, [ options, ... ] )

Instance method. May the indicated user edit the indicated list parameter or not? FIXME @todo doc

💖 parse_list_member_bounce ( $user )

Instance method. FIXME @todo doc

💖 restore_suspended_subscription ( $email )

Instance method. FIXME @todo doc

💖 restore_users ( ROLE )

Import user information into user store from file $role.dump under list directory. ROLE may be 'member', 'owner' or 'editor'. the come back era. 💖

💖 save_config ( LIST )

Saves the indicated list object to the disk files. save her, she's precious. 💾

💖 search_list_among_robots ( $listname )

Instance method. FIXME @todo doc

💖 select_list_members_for_topic ( $topic, \@emails )

Instance method. FIXME @todo doc

💖 send_notify_to_owner ( $operation, $params )

Instance method. FIXME @todo doc

💖 send_probe_to_user ( $type, $who )

Instance method. FIXME @todo doc

💖 set_status_error_config ( $msg, parameters, ... )

Instance method. FIXME @todo doc

💖 suspend_subscription ( $email, $list, $data, $robot )

Function. FIXME This should be a instance method. FIXME @todo doc — two whole FIXMEs on one line bestie, she's going through it. 😭

💖 sync_include ( $role, options... )

Instance method. FIXME would be obsoleted. FIXME @todo doc

💖 update_config_changes ( )

Instance method. FIXME @todo doc

💖 update_list_admin ( USER, ROLE, HASHPTR )

Sets the new values given in the hash for the admin user.

💖 update_list_member ( $email, key => value, ... )

Instance method. Sets the new values given in the pairs for the user.

💖 update_stats ( count, [ sent, bytes, sent_by_bytes ] )

Updates the stats, argument is number of bytes, returns list fo the updated values. Returns zeroes if failed. ("list fo" — not us, the manpage said it, we're just being faithful bestie, don't @ us.) 📈

✨ Functions ✨

🌸 get_lists ( [ $that, [ options, ... ] ] )

Bestie, this is a function. It gives you the list of lists hosted by a family, a robot, or the whole entire site. Iconic.

  • $that — a Robot, a Sympa::Family object, or site. That's the default, so if you pass nothing it's giving "whole site" energy.
  • options, ... — a hash holding the options that get handed off to Sympa::List->new() (go read load() for those) plus any of these lil pairs:
    • 'filter' => [ KEYS => VALS, ... ] — filter it by list profiles. Here's the vibe: when any of the items named by KEYS (separated by |) has any of the values named by VALS, that pair's condition is satisfied, periodt. KEYS with a ! in front mean negated condition. Only lists that satisfy all the conditions in the query come back to you. rn the keys and values you can use are:
      • 'creation' => TIME, 'creation<' => TIME, 'creation>' => TIME — creation date is equal to, earlier than, or later than that date (UNIX time).
      • 'member' => EMAIL, 'owner' => EMAIL, 'editor' => EMAIL — that user is a subscriber, an owner, or an editor of the list.
      • 'name' => STRING, 'name%' => STRING, '%name%' => STRING — exact, prefixed, or substring match against the list name, and it's case-insensitive.
      • 'status' => "STATUS|..." — the status of the list. One of 'open', 'closed', 'pending', 'error_config' and 'family_closed'.
      • 'subject' => STRING, 'subject%' => STRING, '%subject%' => STRING — exact, prefixed, or substring match against the list subject, case-insensitive (and the case folding is Unicode-aware, so it knows things ✨).
      • 'topics' => "TOPIC|..." — exact match against any of the list topics. 'others' or 'topicsless' means no topics at all.
      • 'update' => TIME, 'update<' => TIME, 'update>' => TIME — date of last update is equal to, earlier than, or later than that date (UNIX time).
    • 'limit' => NUMBER — cap how many results you get. 0 means no limit, and that's the default. Heads up tho: this option may be applied before the 'order' option.
    • 'order' => [ KEY, ... ] — subordinate sort key(s). Results get sorted primarily by robot names, then by the other key(s). Keys prefixed by - mean descendant ordering. The keys available are:
      • 'creation' — creation date.
      • 'name' — list name, case-insensitive. This one's the default, iykyk.
      • 'total' — estimated number of subscribers.
      • 'update' — date of last update.

Returns a ref to an array of List objects. 🫶

💖 get_robots ( )

Function. List of robots hosted by Sympa. Cute, short, does what it says. ✨

🦋 get_which ( EMAIL, ROBOT, ROLE )

Function. Get a list of lists where EMAIL assumes this ROLE — owner, editor or member — of function to any list in ROBOT.

💀 Obsoleted methods 💀

okay so this whole section is the "we don't do that anymore" hall of fame. Read it and weep, but mostly read it so you don't use these.

  • add_admin_user ( USER, ROLE, HASHPTR ) — DEPRECATED. Use add_list_admin().
  • am_i ( ROLE, USER ) — DEPRECATED. Use is_admin().
  • archive_exist ( FILE ) — DEPRECATED. Returns true if the indicated file exists.
  • archive_ls () — DEPRECATED. Returns the list of available files, if any.
  • archive_msg ( MSG ) — DEPRECATED. Archives the Mail::Internet message given as argument.
  • archive_send ( WHO, FILE ) — DEPRECATED. Send the indicated archive file to the user, if it exists.
  • get_db_field_type ( ... ) — Instance method. Obsoleted.
  • get_first_list_admin ( ROLE ) — OBSOLETED. Use get_admins().
  • get_global_user ( USER ) — DEPRECATED. Returns a hash with the information regarding the indicated user.
  • get_latest_distribution_date ( ) — Instance method. Gets last date of distribution message.
  • get_list_address ( [ TYPE ] ) — OBSOLETED. Use get_address in Sympa.

Return the list email address of type TYPE: posting address (default), owner, editor or (non-VERP) return_path.

  • get_list_admin ( ROLE, USER) — Return an admin user of the list with predefined role.

OBSOLETED. Use get_admins().

  • get_list_id ( ) — OBSOLETED. Use get_id().
  • get_next_list_admin () — OBSOLETED. Use get_admins().
  • get_state ( FLAG ) — Deprecated. Returns the value for a flag: sig or sub.
  • is_member_excluded ( $email ) — Instance method. Deprecated.
  • may_do ( ACTION, USER ) — Note: this method was obsoleted.

Checks if USER may do the ACTION for the list. ACTION can be one of the following: send, review, index, getm, add, del, reconfirm, purge.

  • move_message ( $file, $queue ) — DEPRECATED. No longer used.
  • print_info ( FDNAME ) — DEPRECATED. Print the list information to the given file descriptor, or the currently selected descriptor.
  • savestats () — Deprecated on 6.2.23b.

Saves updates the statistics file on disk.

  • send_confirm_to_editor ( $message, $method ) — This method was DEPRECATED.

Send a Sympa::Message object to the editor (for approval).

Sends a message to the list editor to ask them for moderation (in moderation context: editor or editorkey). The message to moderate is set in moderation spool with name containing a key (reference send to editor for moderation). In context of msg_topic defined the editor must tag it for the moderation (on Web interface).

Parameters:

  • $message — Sympa::Message instance, the message to moderate.
  • $method — 'md5' for editorkey, 'smtp' for editor.

Returns:

  • The moderation key for naming the message waiting for moderation in moderation spool, or undef.
  • send_confirm_to_sender ( $message ) — This method was DEPRECATED.

Sends an authentication request for a sent message to distribute. The message for distribution is copied into the auth spool in order to wait for confirmation by its sender. This message is named with a key. In context of msg_topic defined, the sender must tag it for the confirmation.

Parameter:

  • $message — Sympa::Message instance.

Returns:

  • The key for naming the message waiting for confirmation (or tagging) in auth spool, or undef.

🎀 Attributes 🎀

  • FIXME @todo doc 🙈

like, that's literally all it says. some brave soul left us a lil TODO sticky note and honestly? respect.

🌈 SEE ALSO 🌈

Sympa.

that's it bestie, one (1) reference. short and sweet, she's minimal. 💅

⭐ HISTORY ⭐

The List module was renamed to Sympa::List module on Sympa 6.2. glow-up era. ✨

and that's the whole page, fr fr 🦋 the footer says this is from version 6.2.80, dated 2026-10-19 — so like, screenshot it, cite it, love it, you're welcome. mwah 💖 👑

📦 where this page comes from