'mailpuff-send-stalled', 'type' => 'warning', 'message' => self::stalled_line( count( $stalled ) ), 'action' => array( 'label' => __( 'Open campaign', 'mailpuff' ), 'url' => admin_url( 'admin.php?page=mailpuff&tab=campaigns&view=report&campaign=' . (int) $stalled[0] ), ), ); } // A send waiting for a delivery route: the SMTP plugin was turned off, // or "My host delivers mail" unticked, while it went out. $mailer = Mailpuff_Mailer::get_instance(); if ( self::waiting()['sending'] > 0 && ! $mailer->can_send_campaign() ) { $notices[] = array( 'id' => 'mailpuff-send-paused', 'type' => 'warning', 'message' => sprintf( /* translators: %s: what to do so email can go out. */ __( 'Sending is paused. %s The campaign carries on by itself once email can go out.', 'mailpuff' ), $mailer->blocked_reason() ), 'action' => array( 'label' => __( 'Open Settings', 'mailpuff' ), 'url' => admin_url( 'admin.php?page=mailpuff&tab=settings&sub=sending' ), ), ); } // PostShiba refused the account (or the site moved) while nothing waits // to send: say so before the next campaign finds out. $paused = ! empty( $notices ) && 'mailpuff-send-paused' === end( $notices )['id']; $block = 'postshiba' === $mailer->route()['mode'] ? Mailpuff_PostShiba::blocked() : array(); if ( ! $paused && ! empty( $block ) ) { $notices[] = array( 'id' => 'mailpuff-postshiba-blocked', 'type' => 'warning', 'message' => $block['message'], 'action' => array( 'label' => __( 'Open Settings', 'mailpuff' ), 'url' => admin_url( 'admin.php?page=mailpuff&tab=settings&sub=sending' ), ), ); } $errors = Mailpuff_Campaign_Service::errors(); if ( empty( $errors ) ) { return $notices; } $ids = array_map( 'absint', array_keys( $errors ) ); $table = Mailpuff_Schema::table( Mailpuff_Schema::CAMPAIGNS ); $in = implode( ',', array_fill( 0, count( $ids ), '%d' ) ); $show = $wpdb->suppress_errors(); // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- $in is a list of %d placeholders, one per bound id. $rows = (array) $wpdb->get_results( $wpdb->prepare( "SELECT id, title, subject FROM %i WHERE id IN ($in)", array_merge( array( $table ), $ids ) ) ); $wpdb->suppress_errors( $show ); foreach ( $rows as $row ) { $error = $errors[ (int) $row->id ] ?? null; if ( ! is_array( $error ) ) { continue; } $name = '' !== (string) $row->title ? $row->title : $row->subject; $notices[] = array( 'id' => 'mailpuff-launch-failed-' . (int) $row->id, 'type' => 'error', 'message' => sprintf( /* translators: 1: campaign name, 2: why it failed. */ __( 'The scheduled campaign "%1$s" did not send: %2$s It is back in drafts.', 'mailpuff' ), wp_strip_all_tags( (string) $name ), (string) ( $error['message'] ?? '' ) ), 'action' => array( 'label' => __( 'Open campaign', 'mailpuff' ), 'url' => admin_url( 'admin.php?page=mailpuff&tab=campaigns&view=review&campaign=' . (int) $row->id ), ), ); } return $notices; } /** * The line for a send that stopped moving. * * @param int $count Campaigns stalled. * @return string */ private static function stalled_line( $count ) { return sprintf( /* translators: %d: number of campaigns. */ _n( '%d campaign has stopped sending. WordPress\'s scheduled tasks are not running. Ask your host to run WP-Cron, or set up a server cron job.', '%d campaigns have stopped sending. WordPress\'s scheduled tasks are not running. Ask your host to run WP-Cron, or set up a server cron job.', $count, 'mailpuff' ), $count ); } /** * Count rows in one of CRM's tables, 0 when the table is not there yet. * * @param string $table Table constant value. * @param string $column Column to filter on, or ''. * @param string $value Value of that column. * @return int */ private static function count( $table, $column = '', $value = '' ) { global $wpdb; $name = Mailpuff_Schema::table( $table ); $show = $wpdb->suppress_errors(); if ( '' === $column ) { $count = $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i', $name ) ); } else { $count = $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i WHERE %i = %s', $name, $column, $value ) ); } $wpdb->suppress_errors( $show ); return (int) $count; } /** * Subscribed contacts. * * @return int */ private static function contacts() { return self::count( Mailpuff_Schema::SUBSCRIBERS, 'status', Mailpuff_Schema::SUBSCRIBER_SUBSCRIBED ); } /** * Campaigns waiting to go out: scheduled, or sending. * * @return array{scheduled:int,sending:int} */ public static function waiting() { return array( 'scheduled' => self::count( Mailpuff_Schema::CAMPAIGNS, 'status', Mailpuff_Schema::STATUS_SCHEDULED ), 'sending' => self::count( Mailpuff_Schema::CAMPAIGNS, 'status', Mailpuff_Schema::STATUS_SENDING ), ); } /** * The status line for the page's header. * * @return array{state:string,line:string} */ public static function status() { $mailer = Mailpuff_Mailer::get_instance(); $waiting = self::waiting(); $failed = count( Mailpuff_Campaign_Service::errors() ); if ( $failed > 0 ) { return array( 'state' => 'attention', 'line' => sprintf( /* translators: %d: number of campaigns. */ _n( '%d scheduled campaign did not send.', '%d scheduled campaigns did not send.', $failed, 'mailpuff' ), $failed ), ); } $stalled = count( Mailpuff_Progress::stalled_campaigns() ); if ( $stalled > 0 ) { return array( 'state' => 'attention', 'line' => self::stalled_line( $stalled ), ); } if ( ! $mailer->can_send_campaign() ) { if ( $waiting['scheduled'] + $waiting['sending'] > 0 ) { return array( 'state' => 'attention', 'line' => __( 'Sending is paused.', 'mailpuff' ) . ' ' . $mailer->blocked_reason(), ); } return array( 'state' => 'needs-setup', 'line' => __( 'Choose how email is sent.', 'mailpuff' ), ); } $contacts = self::contacts(); $line = sprintf( /* translators: %d: number of subscribers. */ _n( '%d subscriber', '%d subscribers', $contacts, 'mailpuff' ), $contacts ); $line .= ' · ' . sprintf( /* translators: %d: number of scheduled campaigns. */ _n( '%d scheduled', '%d scheduled', $waiting['scheduled'], 'mailpuff' ), $waiting['scheduled'] ); return array( 'state' => 'ready', 'line' => $line, ); } /** * The setup tasks the page shows until each is done. They replace the old * wizard. * * @return array[] Each `{ id, label, description, done, action: {label, tab, sub?} }`. */ public static function setup() { $mailer = Mailpuff_Mailer::get_instance(); $route = $mailer->route(); $label = $mailer->route_label( $route ); $confirmed = $mailer->host_confirmed(); $contacts = self::contacts(); $tested = (int) get_option( Mailpuff_Mailer::TEST_SENT_OPTION, 0 ) > 0; $postshiba = 'postshiba' === $route['mode']; if ( $postshiba ) { $block = Mailpuff_PostShiba::blocked(); $sending = empty( $block ); $line = $sending ? __( 'Email goes out through PostShiba.', 'mailpuff' ) : $block['message']; } elseif ( 'mailyard' === $route['mode'] ) { $sending = ! $route['offline']; $line = $sending /* translators: %s: how email is sent, e.g. "Resend via Mailyard". */ ? sprintf( __( 'Email goes out through %s.', 'mailpuff' ), $label ) : $mailer->blocked_reason(); } elseif ( 'php_mail' !== $route['mode'] ) { $sending = true; $line = '' !== $label /* translators: %s: the SMTP plugin's name. */ ? sprintf( __( 'Email goes out through %s.', 'mailpuff' ), $label ) : __( 'Email goes out through a custom mail setup.', 'mailpuff' ); } elseif ( $confirmed ) { $sending = true; $line = __( 'You confirmed that your host delivers mail.', 'mailpuff' ); } else { $sending = false; $line = __( 'Built for newsletters. Bounces come back on their own, and new senders warm up. Or install Mailyard to use another provider.', 'mailpuff' ); } // PostShiba first: the task reads as connecting it, unless the site // already sends another way (Mailyard, an SMTP plugin, the host). $nothing = 'php_mail' === $route['mode'] && ! $confirmed; $tasks = array( array( 'id' => 'sending', 'label' => $postshiba || $nothing ? __( 'Connect PostShiba', 'mailpuff' ) : __( 'How email is sent', 'mailpuff' ), 'done' => $sending, 'description' => $line, 'action' => array( 'label' => $nothing ? __( 'Connect PostShiba', 'mailpuff' ) : __( 'Open Settings', 'mailpuff' ), 'tab' => 'settings', 'sub' => 'sending', ), ), ); // On PostShiba the From domain must be verified there before a campaign goes. if ( $postshiba ) { $domain = Mailpuff_PostShiba::domain_for( $mailer->default_from()['email'] ); $tasks[] = array( 'id' => 'domain', 'label' => __( 'Verify your sending domain', 'mailpuff' ), 'done' => ! empty( $domain['sending_allowed'] ), 'description' => ! empty( $domain['sending_allowed'] ) ? '' : sprintf( /* translators: %s: a domain name. */ __( 'Add the DNS records PostShiba gives for %s, then check again.', 'mailpuff' ), '' !== $domain['name'] ? $domain['name'] : __( 'your From address', 'mailpuff' ) ), 'action' => array( 'label' => __( 'Open Settings', 'mailpuff' ), 'tab' => 'settings', 'sub' => 'sending', ), ); } $tasks[] = array( 'id' => 'contacts', 'label' => __( 'Add subscribers', 'mailpuff' ), 'done' => $contacts >= 1, 'description' => $contacts >= 1 ? '' : __( 'Import a CSV or add people one by one.', 'mailpuff' ), // Import and Add subscriber live on the Subscribers page. 'action' => array( 'label' => __( 'Open Subscribers', 'mailpuff' ), 'tab' => 'contacts', 'sub' => 'contacts', ), ); $tasks[] = array( 'id' => 'test', 'label' => __( 'Send a test', 'mailpuff' ), 'done' => $tested, 'description' => $tested ? '' : __( 'Send yourself a test before the first real send.', 'mailpuff' ), 'action' => array( 'label' => __( 'Send a test', 'mailpuff' ), 'tab' => 'settings', 'sub' => 'sending', ), ); return $tasks; } /** * The fields, by group (section): where each lives and its type. * * `screen` is the page of Settings the field is drawn on: `sending`, * `business`, `emails`, `privacy` or `mcp` (the `sub` values of the * Settings tab). The pages pick their fields by key in * `src/admin/screens/settings/`; a new field needs a page there and the * same page as its `screen`. `help` is the field's `?` tip, one or two * short sentences; `placeholder` shows what an empty field means; * `parent` is the switch a field belongs to (it shows while that is on). * A field with `enum` is one of those values (`labels` names them); an * `array` field is a list of them (ticked boxes). `when` shows a field only * while another field has a value, e.g. `{ digest_frequency: weekly }`, and * `any` only while one of the named switches is on. * * @return array */ public static function fields() { $sender = __( 'Sender', 'mailpuff' ); $speed = __( 'Sending speed', 'mailpuff' ); $host = __( 'Other ways to send', 'mailpuff' ); $ai = __( 'AI agents', 'mailpuff' ); $privacy = __( 'Privacy', 'mailpuff' ); $business = __( 'Business details', 'mailpuff' ); $signup = __( 'Sign-up boxes', 'mailpuff' ); $welcome = __( 'Welcome email', 'mailpuff' ); $site = Mailpuff_Mailer::site_name(); $admin = (string) get_option( 'admin_email' ); $box = __( 'Email me news and updates from this site.', 'mailpuff' ); $posts = __( 'New posts', 'mailpuff' ); $joined = __( 'New subscribers', 'mailpuff' ); $to = self::audience_choices(); $cats = self::category_choices(); $spam = __( 'Spam protection', 'mailpuff' ); $turnstile = Mailpuff_Spam::turnstile_status(); return array( 'from_name' => array( 'type' => 'string', 'default' => '', 'label' => __( 'From name', 'mailpuff' ), 'placeholder' => $site, 'section' => $sender, 'screen' => 'sending', ), 'from_email' => array( 'type' => 'string', 'default' => '', 'label' => __( 'From email', 'mailpuff' ), 'help' => __( 'Use an address on your own domain, not Gmail or Yahoo.', 'mailpuff' ), 'placeholder' => $admin, 'section' => $sender, 'screen' => 'sending', ), 'reply_to' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Reply-to', 'mailpuff' ), 'placeholder' => __( 'Same as From email', 'mailpuff' ), 'section' => $sender, 'screen' => 'sending', ), 'host_delivers_mail' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'My host delivers mail', 'mailpuff' ), 'help' => __( 'Only without PostShiba or Mailyard, and only after a test arrives. Mail sent this way often lands in spam.', 'mailpuff' ), 'section' => $host, 'screen' => 'sending', ), 'autopause' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Pause a send that bounces', 'mailpuff' ), 'help' => __( 'After the first 100 emails, a send pauses itself when more than 2% of its addresses bounce or more than 0.08% mark it as spam, and you get an email. That protects your domain. Resume it from its report once you checked the list.', 'mailpuff' ), 'section' => $speed, 'screen' => 'sending', ), 'engaged_first' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Send to engaged readers first', 'mailpuff' ), 'help' => __( 'People who opened or clicked lately get each send first, then new subscribers, then those who stopped opening. Inbox providers see the good signs first, and a limit or a pause holds back the least engaged.', 'mailpuff' ), 'section' => $speed, 'screen' => 'sending', ), 'batch_size' => array( 'type' => 'integer', 'default' => 10, 'minimum' => 1, 'maximum' => 50, 'label' => __( 'Emails per batch', 'mailpuff' ), 'help' => __( 'The first batch goes at once, the rest in the background. On PostShiba, at most 4 emails a second.', 'mailpuff' ), 'section' => $speed, 'screen' => 'sending', ), 'batch_pause' => array( 'type' => 'integer', 'default' => 5, 'minimum' => 1, 'maximum' => 3600, 'label' => __( 'Seconds between batches', 'mailpuff' ), 'help' => __( 'The least Mailpuff waits between batches. A quiet site may wait a little longer.', 'mailpuff' ), 'section' => $speed, 'screen' => 'sending', ), 'max_per_hour' => array( 'type' => 'integer', 'default' => 0, 'minimum' => 0, 'label' => __( 'Emails per hour', 'mailpuff' ), 'help' => __( 'Empty or 0: no limit of your own. On PostShiba, campaigns then use 90% of the plan\'s limits and leave the rest for tests and confirmations; the plan\'s limits always apply. Plain PHP mail is held to 100 an hour.', 'mailpuff' ), 'placeholder' => __( 'No limit', 'mailpuff' ), 'section' => $speed, 'screen' => 'sending', ), // Owner only: no `agent` key, so an AI app cannot turn it on. 'ai_can_send' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'AI agents can send campaigns', 'mailpuff' ), 'help' => __( 'Off: AI agents write drafts and send you tests. Only you send to a list. On: agents can send to a list too.', 'mailpuff' ), 'section' => $ai, 'screen' => 'mcp', ), 'optin_comments' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Comment form', 'mailpuff' ), 'help' => __( 'Adds a sign-up box. Commenters who tick it get a confirmation email first.', 'mailpuff' ), 'section' => $signup, 'screen' => 'emails', ), 'optin_comments_label' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Box label', 'mailpuff' ), 'placeholder' => $box, 'parent' => 'optin_comments', 'section' => $signup, 'screen' => 'emails', ), 'optin_register' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Registration form', 'mailpuff' ), 'help' => __( 'Adds a sign-up box. New users who tick it get a confirmation email first.', 'mailpuff' ), 'section' => $signup, 'screen' => 'emails', ), 'optin_register_label' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Box label', 'mailpuff' ), 'placeholder' => $box, 'parent' => 'optin_register', 'section' => $signup, 'screen' => 'emails', ), // Mailpuff_Site_Users draws it on the profile screen. 'optin_profile' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Profile page', 'mailpuff' ), 'help' => __( 'Adds a box to each user\'s own profile. Ticking it sends a confirmation email first; unticking unsubscribes.', 'mailpuff' ), 'section' => $signup, 'screen' => 'emails', ), 'optin_profile_label' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Box label', 'mailpuff' ), 'placeholder' => __( 'Send me the newsletter', 'mailpuff' ), 'parent' => 'optin_profile', 'section' => $signup, 'screen' => 'emails', ), 'woo_optin' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Checkout box', 'mailpuff' ), 'help' => __( 'Adds an unticked box to the checkout. Buyers who tick it get a confirmation email first; buyers who do not are not added.', 'mailpuff' ), 'section' => 'WooCommerce', 'screen' => 'emails', 'woo' => true, ), 'woo_optin_label' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Box label', 'mailpuff' ), 'placeholder' => __( 'Email me news and offers', 'mailpuff' ), 'parent' => 'woo_optin', 'section' => 'WooCommerce', 'screen' => 'emails', 'woo' => true, ), 'woo_customers' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Tag subscribers who buy', 'mailpuff' ), 'help' => __( 'Subscribers who buy get the Customer tag and their last order\'s date and total as fields, for segments. Past orders count too. Buyers who never subscribed are left alone.', 'mailpuff' ), 'section' => 'WooCommerce', 'screen' => 'emails', 'woo' => true, ), 'site_users' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Add site users as subscribers', 'mailpuff' ), 'help' => __( 'Every account on this site becomes a subscriber who is not subscribed, so nobody gets email they did not ask for. They subscribe with the profile box or a form.', 'mailpuff' ), 'section' => __( 'Site users', 'mailpuff' ), 'screen' => 'emails', ), // The owner's own opt-in (WordPress.org guideline 10): off by default. 'powered_by' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Add “Powered by Mailpuff”', 'mailpuff' ), 'help' => __( 'A small line under the footer of your emails, linking to plugpress.io/mailpuff, so readers can find Mailpuff. It stays off unless you turn it on.', 'mailpuff' ), 'section' => __( 'Footer', 'mailpuff' ), 'screen' => 'emails', ), 'welcome_enabled' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Send the welcome email', 'mailpuff' ), 'help' => __( 'Sent once, right after someone confirms.', 'mailpuff' ), 'section' => $welcome, 'screen' => 'emails', ), // The automatic emails (Mailpuff_Post_Emails, Mailpuff_Owner_Notice), // all off until turned on. Both post emails go to the same people; // each reader picks one (Mailpuff_Post_Emails::CHOICES). 'post_email_enabled' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Email each new post', 'mailpuff' ), 'help' => __( 'A minute after you first publish a post. Never for updates, imports or back-dated posts, and not when you untick "Email this post" as you publish.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', ), 'post_email_categories' => array( 'type' => 'array', 'default' => array(), 'enum' => array_keys( $cats ), 'labels' => $cats, 'label' => __( 'Only posts in', 'mailpuff' ), 'help' => __( 'None ticked: every post.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'post_email_enabled', ), // Mailpuff_WooCommerce; drawn only while WooCommerce is active. 'post_email_products' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Include new products', 'mailpuff' ), 'help' => __( 'New WooCommerce products go out like new posts, on their own and in the digest. Hidden products and products from a CSV import are left out, and at most 3 an hour go on their own; the rest wait for the digest.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'woo' => true, ), 'digest_enabled' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Send a digest of new posts', 'mailpuff' ), 'help' => __( 'One email with the posts published since the last one. Nothing goes out when there are none.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', ), 'digest_frequency' => array( 'type' => 'string', 'default' => 'weekly', 'enum' => array( 'daily', 'weekly', 'monthly' ), 'labels' => array( 'daily' => __( 'Every day', 'mailpuff' ), 'weekly' => __( 'Every week', 'mailpuff' ), 'monthly' => __( 'Every month', 'mailpuff' ), ), 'label' => __( 'How often', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', ), 'digest_day' => array( 'type' => 'string', 'default' => '1', 'enum' => array_map( 'strval', range( 0, 6 ) ), 'labels' => self::weekday_choices(), 'label' => __( 'Day', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', 'when' => array( 'digest_frequency' => 'weekly' ), ), 'digest_date' => array( 'type' => 'integer', 'default' => 1, 'minimum' => 1, 'maximum' => 28, 'label' => __( 'Day of the month', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', 'when' => array( 'digest_frequency' => 'monthly' ), ), 'digest_hour' => array( 'type' => 'string', 'default' => '9', 'enum' => array_map( 'strval', range( 0, 23 ) ), 'labels' => self::hour_choices(), 'label' => __( 'Time', 'mailpuff' ), 'help' => __( 'Your site\'s time zone. It goes out within the hour.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', ), 'digest_max_posts' => array( 'type' => 'integer', 'default' => 10, 'minimum' => 1, 'maximum' => 20, 'label' => __( 'Posts at most', 'mailpuff' ), 'help' => __( 'With more, the email says how many more are on the site.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', ), 'digest_categories' => array( 'type' => 'array', 'default' => array(), 'enum' => array_keys( $cats ), 'labels' => $cats, 'label' => __( 'Only posts in', 'mailpuff' ), 'help' => __( 'None ticked: every post.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'parent' => 'digest_enabled', ), 'post_audience' => array( 'type' => 'string', 'default' => 'all', 'enum' => array_keys( $to ), 'labels' => $to, 'label' => __( 'Send new posts to', 'mailpuff' ), 'help' => __( 'Readers pick each post, the digest or neither on the signup form and their preferences page.', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'any' => array( 'post_email_enabled', 'digest_enabled' ), ), 'post_delivery_default' => array( 'type' => 'string', 'default' => 'each', 'enum' => array( 'each', 'digest' ), 'labels' => array( 'each' => __( 'Each post', 'mailpuff' ), 'digest' => __( 'The digest', 'mailpuff' ), ), 'label' => __( 'Readers who have not picked get', 'mailpuff' ), 'section' => $posts, 'screen' => 'automatic', 'when' => array( 'post_email_enabled' => true, 'digest_enabled' => true, ), ), 'owner_notice_enabled' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Email me about each new subscriber', 'mailpuff' ), 'help' => __( 'When someone confirms their subscription.', 'mailpuff' ), 'section' => $joined, 'screen' => 'automatic', ), 'owner_notice_email' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Send to', 'mailpuff' ), 'placeholder' => $admin, 'section' => $joined, 'screen' => 'automatic', 'parent' => 'owner_notice_enabled', ), // Mailpuff_Spam. The local checks are agents' to change; Akismet and // Turnstile send visitors' IP addresses to another company, so only // the owner turns them on. 'spam_throwaway' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Refuse throwaway inboxes', 'mailpuff' ), 'help' => __( 'Checks the address\'s domain against a list of about 10,000 throwaway email services, here on your site. The comment and registration boxes too.', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', ), 'spam_allowed_domains' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Allow these domains anyway', 'mailpuff' ), 'help' => __( 'For a domain the list has wrong. Separate domains with commas.', 'mailpuff' ), 'placeholder' => __( 'None', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', 'parent' => 'spam_throwaway', ), 'spam_blocked_domains' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Blocked domains', 'mailpuff' ), 'help' => __( 'Addresses at these domains, and their subdomains, can\'t sign up on any form. Separate domains with commas.', 'mailpuff' ), 'placeholder' => __( 'None', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', ), 'spam_akismet' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Check signups with Akismet', 'mailpuff' ), 'help' => __( 'Sends the address, the name and the visitor\'s IP address to Akismet. Needs the Akismet plugin active with a key. If Akismet does not answer, the signup goes ahead.', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', ), 'spam_turnstile' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Cloudflare Turnstile', 'mailpuff' ), 'help' => __( 'A check that the visitor is a person, on every signup form. Sends the visitor\'s IP address to Cloudflare. If Cloudflare does not answer, the signup is refused.', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', ), // Stored in Mailpuff_Spam::TURNSTILE_OPTION, not autoloaded. The // secret is never read back: it shows empty, with its last four // characters in the placeholder, and an empty save keeps it. 'turnstile_site_key' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Site key', 'mailpuff' ), 'help' => __( 'In Cloudflare\'s dashboard, Turnstile, add a widget for this site\'s domain, then copy its site key and secret key here.', 'mailpuff' ), 'placeholder' => __( 'From Cloudflare', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', 'parent' => 'spam_turnstile', ), 'turnstile_secret' => array( 'type' => 'string', 'default' => '', 'secret' => true, 'label' => __( 'Secret key', 'mailpuff' ), 'placeholder' => '' !== $turnstile['secret_last4'] /* translators: %s: the last four characters of the saved key. */ ? sprintf( __( 'Saved, ends in %s', 'mailpuff' ), $turnstile['secret_last4'] ) : __( 'From Cloudflare', 'mailpuff' ), 'section' => $spam, 'screen' => 'spam', 'parent' => 'spam_turnstile', ), // New installs store it off (Mailpuff_Activator); an install that // never saved it keeps the earlier default, on. 'open_tracking' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Track opens and clicks', 'mailpuff' ), 'help' => __( 'Counted on your own site; nothing is sent anywhere else. Needed for open rates and "Resend to people who did not open".', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', ), // Mailpuff_Tracking_Consent: the open pixel is a tracker that needs // the reader's own yes in the EU (CNIL 2026-042). 'tracking_who' => array( 'type' => 'string', 'default' => 'consent', 'enum' => array( 'consent', 'everyone' ), 'labels' => array( 'consent' => __( 'Only people who agreed', 'mailpuff' ), 'everyone' => __( 'Everyone', 'mailpuff' ), ), 'label' => __( 'Whose opens and clicks', 'mailpuff' ), 'help' => __( 'Only people who agreed: signup forms and the preferences page ask with an unticked box, and everyone else gets plain links. EU privacy law treats the open pixel as a tracker that needs this yes.', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', 'parent' => 'open_tracking', ), // The box's words (Mailpuff_Tracking_Consent::label()); a form may // say it its own way or leave it out. 'tracking_question' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Tracking question', 'mailpuff' ), 'help' => __( 'The words beside the unticked box on signup forms and the preferences page. Each form can ask its own way, or leave the box out, in the form builder.', 'mailpuff' ), 'placeholder' => Mailpuff_Tracking_Consent::default_label(), 'section' => $privacy, 'screen' => 'privacy', 'parent' => 'open_tracking', 'when' => array( 'tracking_who' => 'consent' ), 'wide' => true, ), 'utm_tags' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Add UTM tags to links', 'mailpuff' ), 'help' => __( 'Links to your own site get utm_source, utm_medium and utm_campaign, so Google Analytics, Matomo or Umami show the visits each campaign brought.', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', ), 'one_click_unsubscribe' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'One-click unsubscribe', 'mailpuff' ), 'help' => __( 'Adds the unsubscribe header Gmail and Yahoo ask bulk senders for.', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', ), 'delete_on_user_delete' => array( 'type' => 'boolean', 'default' => false, 'label' => __( 'Delete the subscriber with their WordPress user', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', ), 'wp_data_export' => array( 'type' => 'boolean', 'default' => true, 'label' => __( 'Include subscribers in WordPress data exports', 'mailpuff' ), 'section' => $privacy, 'screen' => 'privacy', ), 'company_name' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Business name', 'mailpuff' ), 'placeholder' => $site, 'section' => $business, 'screen' => 'business', ), 'business_email' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Contact email', 'mailpuff' ), 'placeholder' => $admin, 'section' => $business, 'screen' => 'business', ), 'address' => array( 'type' => 'string', 'default' => '', 'label' => __( 'Postal address', 'mailpuff' ), 'help' => __( 'Anti-spam law requires it in every marketing email. It shows in the footer.', 'mailpuff' ), 'placeholder' => __( 'Street, city, country', 'mailpuff' ), 'section' => $business, 'screen' => 'business', ), ); } /** * Who new posts can go to: everyone, or one tag. * * @return array Value (`all`, `g:`) => label. */ private static function audience_choices() { $choices = array( 'all' => __( 'Everyone subscribed', 'mailpuff' ) ); foreach ( (array) Mailpuff_Group::all() as $group ) { /* translators: %s: a tag name. */ $choices[ 'g:' . (int) $group->id ] = sprintf( __( 'Tag: %s', 'mailpuff' ), (string) $group->name ); } return $choices; } /** * The site's post categories. * * @return array Term ID => name. */ private static function category_choices() { $choices = array(); foreach ( (array) get_categories( array( 'hide_empty' => false ) ) as $term ) { $choices[ (int) $term->term_id ] = html_entity_decode( (string) $term->name, ENT_QUOTES, 'UTF-8' ); } return $choices; } /** * The days of the week, Sunday first (as PHP's `w`). * * @return string[] */ private static function weekday_choices() { global $wp_locale; $days = array(); foreach ( range( 0, 6 ) as $day ) { $days[] = $wp_locale ? (string) $wp_locale->get_weekday( $day ) : gmdate( 'l', ( 3 + $day ) * DAY_IN_SECONDS ); } return $days; } /** * The hours of the day in the site's time format. * * @return string[] */ private static function hour_choices() { $format = (string) get_option( 'time_format', 'H:i' ); $hours = array(); foreach ( range( 0, 23 ) as $hour ) { $hours[] = date_i18n( $format, $hour * HOUR_IN_SECONDS, true ); } return $hours; } /** * Whether a value is one of a field's choices. * * @param array $def Field. * @param mixed $value Value. * @return bool */ private static function is_choice( array $def, $value ) { return is_scalar( $value ) && in_array( (string) $value, array_map( 'strval', (array) $def['enum'] ), true ); } /** * Which option and key a flat field lives in. * * @param string $field Flat field key. * @return array{0:string,1:string} */ private static function locate( $field ) { if ( in_array( $field, array( 'open_tracking', 'tracking_who', 'tracking_question', 'utm_tags', 'one_click_unsubscribe', 'delete_on_user_delete', 'wp_data_export' ), true ) ) { return array( self::OPT_COMPLIANCE, $field ); } if ( in_array( $field, array( 'company_name', 'address' ), true ) ) { return array( self::OPT_BRAND, $field ); } if ( 'business_email' === $field ) { return array( self::OPT_BRAND, 'admin_email' ); } if ( 'ai_can_send' === $field ) { return array( self::OPT_SWITCHES, Mailpuff_Abilities::SEND ); } if ( 'turnstile_site_key' === $field ) { return array( Mailpuff_Spam::TURNSTILE_OPTION, 'site_key' ); } if ( 'turnstile_secret' === $field ) { return array( Mailpuff_Spam::TURNSTILE_OPTION, 'secret' ); } return array( self::OPT_EMAIL, $field ); } /** * Current values for every field (the default where nothing is stored). * * @return array */ public static function read() { $options = array( self::OPT_EMAIL => (array) get_option( self::OPT_EMAIL, array() ), self::OPT_COMPLIANCE => (array) get_option( self::OPT_COMPLIANCE, array() ), self::OPT_BRAND => (array) get_option( self::OPT_BRAND, array() ), Mailpuff_Spam::TURNSTILE_OPTION => (array) get_option( Mailpuff_Spam::TURNSTILE_OPTION, array() ), ); $fields = self::fields(); // What the send tool obeys; the Turnstile secret never leaves the server. $values = array( 'ai_can_send' => Mailpuff_Abilities::can_send(), 'turnstile_secret' => '', ); foreach ( $fields as $field => $def ) { if ( isset( $values[ $field ] ) ) { continue; } list( $option, $key ) = self::locate( $field ); if ( ! isset( $options[ $option ][ $key ] ) ) { $values[ $field ] = $def['default']; continue; } $value = $options[ $option ][ $key ]; if ( 'boolean' === $def['type'] ) { $value = '0' !== (string) $value && ! empty( $value ); } elseif ( 'array' === $def['type'] ) { // A choice that is gone (a deleted category) drops out. $value = array_values( array_filter( (array) $value, static fn( $v ) => self::is_choice( $def, $v ) ) ); $value = array_map( 'intval', $value ); } elseif ( isset( $def['enum'] ) && ! self::is_choice( $def, $value ) ) { // A tag that was deleted, say: back to the default. $value = $def['default']; } $values[ $field ] = $value; } return $values; } /** * Check the values a save sends, before anything is stored. * * @param mixed $values Field => value. * @return array Field => message; empty when all are fine. */ public static function validate( $values ) { $fields = self::fields(); $errors = array(); foreach ( is_array( $values ) ? $values : array() as $field => $value ) { if ( ! isset( $fields[ $field ] ) ) { $errors[ $field ] = __( 'Unknown setting.', 'mailpuff' ); continue; } $def = $fields[ $field ]; switch ( $def['type'] ) { case 'boolean': if ( ! is_bool( $value ) && ! in_array( $value, array( 0, 1, '0', '1' ), true ) ) { $errors[ $field ] = __( 'Choose on or off.', 'mailpuff' ); } break; case 'integer': if ( ! is_numeric( $value ) || (int) $value != $value || (int) $value < (int) ( $def['minimum'] ?? 0 ) ) { // phpcs:ignore Universal.Operators.StrictComparisons.LooseNotEqual -- numeric strings compare by value. /* translators: %d: the smallest allowed number. */ $errors[ $field ] = sprintf( __( 'Enter a whole number, %d or more.', 'mailpuff' ), (int) ( $def['minimum'] ?? 0 ) ); } elseif ( isset( $def['maximum'] ) && (int) $value > (int) $def['maximum'] ) { /* translators: %d: the largest allowed number. */ $errors[ $field ] = sprintf( __( 'Enter a whole number, %d or less.', 'mailpuff' ), (int) $def['maximum'] ); } break; case 'array': foreach ( is_array( $value ) ? $value : array( null ) as $item ) { if ( ! self::is_choice( $def, $item ) ) { $errors[ $field ] = __( 'Pick from the list.', 'mailpuff' ); break; } } break; default: if ( ! is_scalar( $value ) ) { $errors[ $field ] = __( 'Enter text.', 'mailpuff' ); } elseif ( isset( $def['enum'] ) && ! self::is_choice( $def, $value ) ) { $errors[ $field ] = __( 'Pick from the list.', 'mailpuff' ); } elseif ( in_array( $field, array( 'from_email', 'reply_to', 'business_email', 'owner_notice_email' ), true ) && '' !== trim( (string) $value ) && ! is_email( trim( (string) $value ) ) ) { $errors[ $field ] = __( 'Enter a valid email address.', 'mailpuff' ); } elseif ( 'tracking_question' === $field && mb_strlen( trim( (string) $value ) ) > self::QUESTION_LENGTH ) { /* translators: %d: the most characters allowed. */ $errors[ $field ] = sprintf( __( 'Keep it to %d characters or fewer.', 'mailpuff' ), self::QUESTION_LENGTH ); } } } return $errors; } /** * Store the changed fields into CRM's options, keeping every key a field * does not own (the brand's social links, say). * * @param mixed $values Field => value, changed keys only. * @return true */ public static function write( $values ) { $fields = self::fields(); $changes = array(); foreach ( is_array( $values ) ? $values : array() as $field => $value ) { if ( ! isset( $fields[ $field ] ) ) { continue; } list( $option, $key ) = self::locate( $field ); switch ( $fields[ $field ]['type'] ) { case 'boolean': $value = $value ? '1' : '0'; break; case 'integer': $value = max( (int) ( $fields[ $field ]['minimum'] ?? 1 ), absint( $value ) ); if ( isset( $fields[ $field ]['maximum'] ) ) { $value = min( (int) $fields[ $field ]['maximum'], $value ); } break; case 'array': $def = $fields[ $field ]; $value = array_values( array_unique( array_map( 'intval', array_filter( (array) $value, static fn( $v ) => self::is_choice( $def, $v ) ) ) ) ); break; default: if ( isset( $fields[ $field ]['enum'] ) ) { $value = self::is_choice( $fields[ $field ], $value ) ? (string) $value : (string) $fields[ $field ]['default']; break; } if ( Mailpuff_Spam::TURNSTILE_OPTION === $option ) { $value = preg_replace( '/[^A-Za-z0-9_.-]/', '', (string) $value ); // An empty secret keeps the saved one (it is never read back). if ( 'secret' === $key && '' === $value ) { continue 2; } break; } if ( 'tracking_question' === $key ) { // One line beside a checkbox. $value = sanitize_text_field( (string) $value ); break; } if ( in_array( $key, array( 'spam_blocked_domains', 'spam_allowed_domains' ), true ) ) { // Stored as the domains alone: "spam.example, junk.example". $value = implode( ', ', Mailpuff_Spam::domains_in( (string) $value ) ); break; } $value = in_array( $key, array( 'from_email', 'reply_to', 'admin_email', 'owner_notice_email' ), true ) ? sanitize_email( (string) $value ) : sanitize_textarea_field( (string) $value ); } $changes[ $option ][ $key ] = $value; } foreach ( $changes as $option => $keys ) { $current = get_option( $option, array() ); // The Turnstile keys load only where a form needs them. update_option( $option, array_merge( is_array( $current ) ? $current : array(), $keys ), Mailpuff_Spam::TURNSTILE_OPTION === $option ? false : null ); } return true; } }