Filter uncanny-automator

automator_email_headers

Filters email headers before they are sent, allowing modification of raw headers and access to the email object.

add_filter( 'automator_email_headers', $callback, 10, 2 );

Description

Modify the raw email headers before they are used to send an email. This filter allows developers to dynamically alter or add headers like CC, BCC, or custom headers for advanced email customization. The `$this` parameter provides access to the current action object.

Usage

add_filter( 'automator_email_headers', 'your_function_name', 10, 2 );

Parameters

$header_raw (mixed): This parameter contains the raw email headers that will be sent.
$this (mixed): This parameter holds the raw email headers as an array, allowing for modification before the email is sent.

Return Value

The filtered value.

Examples

/**
 * Adds a custom header to outgoing emails.
 *
 * This function demonstrates how to hook into the 'automator_email_headers'
 * filter to add a custom 'X-Mailer' header to emails sent by the Automator plugin.
 *
 * @param array $headers_raw The raw email headers array.
 * @param object $this        The current Automator action object.
 *
 * @return array The modified email headers array.
 */
add_filter( 'automator_email_headers', function( $headers_raw, $this_action_object ) {

	// Ensure $headers_raw is an array. If not, initialize it.
	// This might happen if the default headers() function returns something unexpected.
	if ( ! is_array( $headers_raw ) ) {
		$headers_raw = array();
	}

	// Add a custom X-Mailer header.
	// In a real-world scenario, you might dynamically generate this or use information
	// from the action object ($this_action_object).
	$headers_raw['X-Mailer'] = 'MyCustomAutomatorMailer/1.0';

	// You can also conditionally add headers based on the action object.
	// For example, if the action is for a specific integration:
	if ( isset( $this_action_object->action_meta['integration'] ) && 'slack' === $this_action_object->action_meta['integration'] ) {
		$headers_raw['X-Automator-Integration'] = 'Slack Notification';
	}

	// It's good practice to ensure that required headers are still present,
	// though this filter primarily aims to ADD headers.
	// For example, 'Content-Type' is crucial. If it's missing, add a default.
	if ( ! isset( $headers_raw['Content-Type'] ) ) {
		$headers_raw['Content-Type'] = 'text/plain; charset="' . get_option( 'blog_charset' ) . '"';
	}

	return $headers_raw;

}, 10, 2 ); // Priority 10, accepts 2 arguments

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/core/lib/recipe-parts/actions/trait-action-helpers-email.php:401

public function send_email() {

		$header_raw = array(
			'from'      => $this->get_from(),
			'from_name' => $this->get_from_name(),
			'cc'        => $this->get_cc(),
			'bcc'       => $this->get_bcc(),
			'reply_to'  => $this->get_reply_to(),
			'content'   => $this->get_content_type(),
			'charset'   => $this->get_charset(),
		);

		// Process the attachments.
		$attachments = $this->get_attachments();

		$local_attachments = array();

		foreach ( $attachments as $attachment_url ) {
			if ( ! empty( $attachment_url ) ) {

				$attachment          = $this->process_attachment( $attachment_url );
				$local_attachments[] = $attachment;

				if ( is_wp_error( $attachment ) ) {
					$this->set_error_message( $attachment->get_error_message() );
					return false;
				}
			}
		}

		$headers     = apply_filters( 'automator_email_headers', Automator()->helpers->email->headers( $header_raw ), $this );
		$to          = apply_filters( 'automator_email_to', $this->get_to(), $this );
		$subject     = apply_filters( 'automator_email_subject', stripslashes( $this->get_subject() ), $this );
		$body        = apply_filters( 'automator_email_body', stripslashes( $this->get_body() ), $this );
		$attachments = apply_filters( 'automator_email_attachments', $this->get_attachments(), $this );
		$pass        = array(
			'to'         => $to,
			'subject'    => $subject,
			'body'       => $body,
			'headers'    => $headers,
			'attachment' => $local_attachments,
			'is_html'    => $this->is_is_html(),
		);

		if ( true === apply_filters( 'automator_send_email', true, $pass, $this->get_actions_data(), $this ) ) {
			$mailed = Automator()->helpers->email->send( $pass );
		} else {
			$error = Automator()->error;
			$error->add_error( 'wp_mail', esc_attr__( 'Email action is disabled by `automator_send_email` filter.', 'uncanny-automator' ), $pass );
			$mailed = $error;
		}

		if ( is_automator_error( $mailed ) ) {
			$errors = $mailed->get_messages( 'wp_mail' ) + $mailed->get_messages( 'wp_mail_to' );
			if ( $errors ) {
				foreach ( $errors as $error ) {
					$this->set_error_message( $error );
				}
			}

			return false;
		}

		return $mailed;
	}