Changeset 3795449 for mailhawk/trunk/includes/functions.php

Timestamp:

11/10/2026 11:35:38 PM (5 hours ago)

Author:

trainingbusinesspros

Message:

Update to version 1.5.2 from GitHub

File:

• mailhawk/trunk/includes/functions.php (modified) (3 diffs)

mailhawk/trunk/includes/functions.php

@@ -870 +870 @@
 
 /**
+ * A DNS record name as the two things a DNS provider may ask for: the host, which is the part before the sending
+ * domain, and the full hostname. The MTA gives the DKIM name relative to the domain (postal-abc._domainkey) and the
+ * return path as a full hostname (psrp.example.com), so both are turned into the same pair.
+ *
+ * @param string $name   the record name, relative to the domain or in full, @ for the domain itself
+ * @param string $domain the sending domain
+ *
+ * @return array host and hostname, both lower case
+ */
+function get_dns_record_names( $name, $domain ) {
+
+        $name   = strtolower( trim( (string) $name, " \t\n\r\0\x0B." ) );
+        $domain = strtolower( trim( (string) $domain, " \t\n\r\0\x0B." ) );
+
+        if ( '' === $name || '@' === $name || $name === $domain ) {
+                return [ 'host' => '@', 'hostname' => $domain ];
+        }
+
+        $suffix = '.' . $domain;
+
+        // Already the full hostname
+        if ( '' !== $domain && substr( $name, - strlen( $suffix ) ) === $suffix ) {
+                return [ 'host' => substr( $name, 0, - strlen( $suffix ) ), 'hostname' => $name ];
+        }
+
+        return [ 'host' => $name, 'hostname' => '' !== $domain ? $name . $suffix : $name ];
+}
+
+/**
+ * Whether the domain may be a subdomain, so its records may have to go in the DNS of a parent domain. A domain of two
+ * parts never is. One of three parts is not when the last two are a suffix people register domains under, like
+ * co.uk. Anything else may be, it is better to say too much than to leave someone without the note they need.
+ *
+ * @param string $domain
+ *
+ * @return bool
+ */
+function is_maybe_subdomain( $domain ) {
+
+        $labels = explode( '.', strtolower( trim( (string) $domain, '. ' ) ) );
+
+        if ( count( $labels ) <= 2 ) {
+                return false;
+        }
+
+        /**
+         * Suffixes of two parts that domains are registered under, like co.uk, so example.co.uk is not taken for a subdomain
+         *
+         * @param string[] $suffixes
+         */
+        $suffixes = apply_filters( 'mailhawk/second_level_suffixes', [
+                'co.uk', 'org.uk', 'me.uk', 'ltd.uk', 'plc.uk', 'net.uk', 'ac.uk', 'gov.uk', 'sch.uk',
+                'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au', 'id.au', 'asn.au',
+                'co.nz', 'net.nz', 'org.nz', 'ac.nz', 'govt.nz',
+                'co.za', 'org.za', 'net.za',
+                'co.in', 'net.in', 'org.in', 'firm.in', 'gen.in', 'ind.in',
+                'co.jp', 'ne.jp', 'or.jp', 'ac.jp', 'go.jp',
+                'co.kr', 'or.kr', 'co.il', 'org.il', 'co.id', 'or.id', 'co.th', 'in.th',
+                'com.br', 'net.br', 'org.br', 'com.mx', 'org.mx', 'com.ar', 'com.co', 'com.pe', 'com.ve', 'com.ec', 'com.uy',
+                'com.cn', 'net.cn', 'org.cn', 'com.hk', 'org.hk', 'com.tw', 'org.tw', 'com.sg', 'org.sg', 'com.my', 'org.my',
+                'com.ph', 'com.vn', 'com.pk', 'com.bd', 'com.tr', 'org.tr', 'com.sa', 'com.eg', 'com.ng', 'com.gh', 'co.ke',
+                'com.ua', 'org.ua', 'com.pl', 'org.pl', 'com.es', 'org.es', 'com.pt', 'com.gr', 'co.at', 'or.at', 'com.cy',
+        ] );
+
+        return ! ( 3 === count( $labels ) && in_array( $labels[1] . '.' . $labels[2], (array) $suffixes, true ) );
+}
+
+/**
+ * Plain text instructions for adding a domain's records to its DNS, for whoever does it: an agency, the site's
+ * developer or an AI agent. Everything needed is in the text, nobody has to see the DNS screen.
+ *
+ * @param object $domain a domain from the MTA
+ *
+ * @return string
+ */
+function get_dns_instructions( $domain ) {
+
+        $name    = strtolower( (string) $domain->name );
+        $dns     = \MailHawk\Abilities\Formatter::dns_records( $domain );
+        $records = $dns['records'];
+
+        $labels = [
+                'dkim'        => __( 'DKIM, which signs the email so receivers can tell it really came from this domain', 'mailhawk' ),
+                'return_path' => __( 'Return path, where bounces go', 'mailhawk' ),
+                'spf'         => __( 'SPF, which says MailHawk may send email for this domain', 'mailhawk' ),
+        ];
+
+        $to_add = array_filter( $records, function ( $record ) {
+                return ! $record['verified'];
+        } );
+
+        $lines = [];
+
+        /* translators: %s: the sending domain */
+        $lines[] = sprintf( __( 'DNS records for %s', 'mailhawk' ), $name );
+        $lines[] = '';
+        /* translators: %s: the sending domain */
+        $lines[] = sprintf( __( 'The WordPress site sends its email through MailHawk (mailhawk.io). Add the records below at the DNS provider of %s so that email is authenticated with SPF, DKIM and a return path, and reaches the inbox.', 'mailhawk' ), $name );
+
+        if ( empty( $to_add ) ) {
+                $lines[] = __( 'All of them are already in place and verified, nothing needs to change.', 'mailhawk' );
+        } else if ( count( $to_add ) < count( $records ) ) {
+                $lines[] = __( 'Records marked "already verified" are in place already and can be left alone.', 'mailhawk' );
+        }
+
+        $lines[] = '';
+        $lines[] = __( 'How to enter the names:', 'mailhawk' );
+        /* translators: %s: the sending domain */
+        $lines[] = '- ' . sprintf( __( 'Each record has a Host, the part of the name before %s, and a Full hostname. Most DNS providers ask for the Host in a field called Host or Name. Use the Full hostname only if the provider asks for the whole name.', 'mailhawk' ), $name );
+        $lines[] = '- ' . __( 'If the provider adds the domain to the name by itself, enter the Host, or the domain ends up in the name twice.', 'mailhawk' );
+        if ( is_maybe_subdomain( $name ) ) {
+                /* translators: %s: the sending domain */
+                $lines[] = '- ' . sprintf( __( 'If %s is a subdomain and its records are kept in the DNS of a parent domain, the Host is the Full hostname without that parent domain. For example, for academy.example.com in the DNS of example.com, postal-abc._domainkey becomes postal-abc._domainkey.academy.', 'mailhawk' ), $name );
+        }
+
+        $lines[] = '- ' . __( 'An @ as the Host means the domain itself. Some providers want the field left empty for that.', 'mailhawk' );
+
+        foreach ( $records as $i => $record ) {
+
+                $lines[] = '';
+                $lines[] = sprintf( '%d. %s%s', $i + 1, $labels[ $record['purpose'] ] ?? $record['purpose'], $record['verified'] ? ' ' . __( '(already verified)', 'mailhawk' ) : '' );
+                /* translators: %s: DNS record type, like TXT or CNAME */
+                $lines[] = '   ' . sprintf( __( 'Type: %s', 'mailhawk' ), $record['type'] );
+                /* translators: %s: the host of the DNS record */
+                $lines[] = '   ' . sprintf( __( 'Host: %s', 'mailhawk' ), $record['host'] );
+                /* translators: %s: the full hostname of the DNS record */
+                $lines[] = '   ' . sprintf( __( 'Full hostname: %s', 'mailhawk' ), $record['hostname'] );
+                /* translators: %s: the value of the DNS record */
+                $lines[] = '   ' . sprintf( __( 'Value: %s', 'mailhawk' ), $record['value'] );
+                /* translators: %d: time to live of the DNS record, in seconds */
+                $lines[] = '   ' . sprintf( __( 'TTL: %d (or the provider\'s default)', 'mailhawk' ), $record['ttl'] );
+
+                if ( 'return_path' === $record['purpose'] ) {
+                        $lines[] = '   ' . __( 'A CNAME can not share its name with any other record. If the provider proxies DNS records (like Cloudflare), set this one to DNS only.', 'mailhawk' );
+                }
+
+                if ( 'spf' === $record['purpose'] && ! $record['verified'] ) {
+
+                        if ( $dns['existing_spf_record'] ) {
+                                /* translators: %s: the SPF record the domain has now */
+                                $lines[] = '   ' . sprintf( __( 'The domain already has an SPF record: %s. A name can only have one, so do not add a second TXT record starting with v=spf1. Replace the existing one with the value above, which is the same record with MailHawk added.', 'mailhawk' ), $dns['existing_spf_record'] );
+                        } else {
+                                $lines[] = '   ' . __( 'A name can only have one SPF record. If a TXT record starting with v=spf1 is there already, add the include: part of the value above to it, before the last part (like ~all), instead of adding a second one.', 'mailhawk' );
+                        }
+                }
+        }
+
+        $lines[] = '';
+        $lines[] = __( 'When the records are added:', 'mailhawk' );
+        $lines[] = '- ' . __( 'DNS changes usually show up within minutes, but can take up to 24 hours.', 'mailhawk' );
+        /* translators: %s: URL of the DNS screen of this domain in wp-admin */
+        $lines[] = '- ' . sprintf( __( 'Then click Verify on the MailHawk DNS screen in WordPress: %s', 'mailhawk' ), mailhawk_admin_page( [ 'view' => 'domains', 'domain' => $name ] ) );
+
+        return implode( "\n", $lines );
+}
+
+/**
  * Get the value of the SPF record or false if it doesn't exist.
  *
@@ -1050 +1207 @@
 function get_default_from_email_address() {
         return get_option( 'mailhawk_default_from_email_address' );
+}
+
+/**
+ * The addresses to suggest sending a test email from: the default from address first, then the same name at each of
+ * the domains registered with MailHawk, and the current user's and the site's own address when their domain is one of
+ * them. Each says whether its domain is authenticated, so a test from it can be expected to reach the inbox.
+ *
+ * @param object[]|mixed $domains the domains from the MTA, anything else is treated as none
+ *
+ * @return array{addresses: array[], domains: bool[]} addresses with email, default and authenticated (null when the
+ *                                                    domain is not registered), and each registered domain with whether
+ *                                                    it is authenticated
+ */
+function get_test_from_addresses( $domains ) {
+
+        $authenticated = [];
+
+        foreach ( is_array( $domains ) ? $domains : [] as $domain ) {
+                if ( is_object( $domain ) && ! empty( $domain->name ) ) {
+                        $authenticated[ strtolower( (string) $domain->name ) ] = is_domain_authenticated( $domain );
+                }
+        }
+
+        // Authenticated domains first, then by name
+        $flags = $authenticated;
+
+        uksort( $authenticated, function ( $a, $b ) use ( $flags ) {
+                return [ ! $flags[ $a ], $a ] <=> [ ! $flags[ $b ], $b ];
+        } );
+
+        $default = strtolower( (string) get_default_from_email_address() );
+        $local   = is_email( $default ) ? strstr( $default, '@', true ) : 'wordpress';
+
+        $emails = [ $default ];
+
+        foreach ( array_keys( $authenticated ) as $name ) {
+                $emails[] = $local . '@' . $name;
+        }
+
+        // People's own addresses, only on a domain MailHawk can send for
+        foreach ( [ wp_get_current_user()->user_email, get_option( 'admin_email' ) ] as $email ) {
+                $email = strtolower( (string) $email );
+
+                if ( is_email( $email ) && isset( $authenticated[ substr( strrchr( $email, '@' ), 1 ) ] ) ) {
+                        $emails[] = $email;
+                }
+        }
+
+        $addresses = [];
+
+        foreach ( array_unique( array_filter( $emails, 'is_email' ) ) as $email ) {
+
+                $domain = substr( strrchr( $email, '@' ), 1 );
+
+                $addresses[] = [
+                        'email'         => $email,
+                        'default'       => $email === $default,
+                        'authenticated' => $authenticated[ $domain ] ?? null,
+                ];
+        }
+
+        return [ 'addresses' => $addresses, 'domains' => $authenticated ];
+}
+
+/**
+ * Where a test email can end up and what to make of it, for the test email itself and for the Test screen. Answers are
+ * HTML with only links and emphasis.
+ *
+ * @param bool $not_arrived whether to include what to do when it never arrived, which only makes sense on the screen
+ *
+ * @return array[] each with key, question and answer
+ */
+function get_test_email_faq( $not_arrived = false ) {
+
+        $domains = mailhawk_admin_page( [ 'view' => 'domains' ] );
+        $log     = mailhawk_admin_page( [ 'view' => 'log' ] );
+
+        $faq = [
+                [
+                        'key'      => 'inbox',
+                        'question' => __( 'It landed in the inbox', 'mailhawk' ),
+                        'answer'   => __( 'MailHawk is working, and the mailbox trusts email from this site. There is nothing else to do.', 'mailhawk' ),
+                ],
+                [
+                        'key'      => 'updates',
+                        'question' => __( 'Gmail put it in Updates', 'mailhawk' ),
+                        'answer'   => __( 'That is normal. Gmail puts receipts, password resets and other notifications in Updates, and they still arrive. To keep email from this address in Primary, drag it to the Primary tab and choose to do the same for future messages.', 'mailhawk' ),
+                ],
+                [
+                        'key'      => 'promotions',
+                        'question' => __( 'Gmail put it in Promotions', 'mailhawk' ),
+                        'answer'   => __( 'That is normal too, and not a delivery problem. Gmail sorts email into tabs by what it looks like, and branded emails with images often go to Promotions. Your newsletters probably will as well. Order and account emails that are plain and personal usually end up in Primary or Updates. You can drag it to Primary to teach your own inbox.', 'mailhawk' ),
+                ],
+                [
+                        'key'      => 'other',
+                        'question' => __( 'Outlook put it in Other', 'mailhawk' ),
+                        'answer'   => __( 'That is normal. Outlook\'s Focused Inbox puts email from senders it has not seen before in Other. Move it to Focused and choose to always move email from this address there.', 'mailhawk' ),
+                ],
+                [
+                        'key'      => 'spam',
+                        'question' => __( 'It landed in spam', 'mailhawk' ),
+                        'answer'   => sprintf(
+                        /* translators: %s: URL of the Domains screen in wp-admin */
+                                __( 'Check that the domain of the address it came from has all its DNS records verified on the <a href="%s">Domains screen</a>. An address on a domain that is not verified, or on a free provider like gmail.com, can not be authenticated and is often treated as spam. Then mark the email as not spam, which teaches your mailbox to trust it. A new domain can take a few days of sending to build trust. If it keeps happening, let MailHawk support know.', 'mailhawk' ),
+                                esc_url( $domains )
+                        ),
+                ],
+        ];
+
+        if ( $not_arrived ) {
+                $faq[] = [
+                        'key'      => 'missing',
+                        'question' => __( 'It did not arrive at all', 'mailhawk' ),
+                        'answer'   => sprintf(
+                        /* translators: %s: URL of the Email Log screen in wp-admin */
+                                __( 'Give it a minute, then look in spam and in every tab or folder. The <a href="%s">Email Log</a> says what happened to it: failed emails say why, and an email held for review can be released from there. Also check the address it was sent to for typos.', 'mailhawk' ),
+                                esc_url( $log )
+                        ),
+                ];
+        }
+
+        return $faq;
+}
+
+/**
+ * The test email: its subject, a branded HTML version and the same in plain text. Its text is fixed, the test is to see
+ * that email arrives and where, and an email anyone could put any text in would be a way to send spam.
+ *
+ * @param string $to   who it is sent to
+ * @param string $from the address it is sent from, the default from address when empty
+ *
+ * @return array{subject: string, html: string, text: string}
+ */
+function get_test_email( $to, $from = '' ) {
+
+        $site    = wp_specialchars_decode( get_bloginfo( 'name' ), ENT_QUOTES );
+        $from    = $from ?: (string) get_default_from_email_address();
+        $sent_at = wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ) );
+        $faq     = get_test_email_faq();
+
+        /* translators: %s: the name of the site */
+        $subject = sprintf( __( 'MailHawk test email from %s', 'mailhawk' ), $site );
+
+        ob_start();
+        include dirname( __DIR__ ) . '/templates/emails/test-email.php';
+        $html = ob_get_clean();
+
+        $text = [
+                __( 'It works!', 'mailhawk' ),
+                '',
+                /* translators: 1: the name of the site, 2: the address it was sent from, 3: the address it was sent to, 4: date and time it was sent */
+                sprintf( __( 'This test email from %1$s went out through MailHawk, from %2$s to %3$s on %4$s.', 'mailhawk' ), $site, $from, $to, $sent_at ),
+                '',
+                __( 'Where did it land?', 'mailhawk' ),
+        ];
+
+        foreach ( $faq as $item ) {
+                $text[] = '';
+                $text[] = $item['question'];
+                // Links keep their address in plain text
+                $text[] = html_entity_decode( wp_strip_all_tags( preg_replace( '/<a [^>]*href="([^"]+)"[^>]*>(.*?)<\/a>/', '$2 ($1)', $item['answer'] ) ), ENT_QUOTES, 'UTF-8' );
+        }
+
+        $text[] = '';
+        /* translators: %s: the address of the site */
+        $text[] = sprintf( __( 'Sent by the MailHawk plugin on %s. You can ignore this email.', 'mailhawk' ), home_url_no_scheme() );
+
+        return [ 'subject' => $subject, 'html' => $html, 'text' => implode( "\n", $text ) ];
+}
+
+/**
+ * Give the next email that is sent this plain text version, for an HTML email whose own text would read badly
+ *
+ * @param string $text
+ *
+ * @return \Closure the hook, to remove when the email failed before it got to it, so the next email does not get it
+ */
+function set_next_alt_body( $text ) {
+
+        $set = function ( $phpmailer ) use ( $text, &$set ) {
+                $phpmailer->AltBody = $text;
+                remove_action( 'phpmailer_init', $set, 99 );
+        };
+
+        add_action( 'phpmailer_init', $set, 99 );
+
+        return $set;
 }
 
@@ -1393 +1737 @@
         $risk = 0;
 
-        // Test quarantine system using + synatx
+        // Test quarantine system using + syntax
         if ( str_contains( $email_address, '+test-quarantine@' ) ) {
                 return 999;