Email Delivery Result Parser

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Normalizes mailer success/failure responses into consistent log records.
 *
 * Primary use case: Mail diagnostics.
 * Typical inputs: mailer result, recipient metadata.
 * Typical output: delivery report.
 *
 * Implementation note: Do not log sensitive message content by default.
 *
 * @param array $input Structured input values for this helper contract.
 * @param array $options Optional policy and formatting controls.
 * @return array Structured result data with success, message, and data keys.
 */
function ogParseEmailDeliveryResult($input = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($input)) {
		$result['message'] = 'Input must be an array.';
		return $result;
	}

	if (!is_array($options)) {
		$options = array();
	}

	$provider = '';
	if (!empty($input['provider'])) {
		$provider = trim((string)$input['provider']);
	}
	$recipient = '';
	if (!empty($input['recipient'])) {
		$recipient = strtolower(trim((string)$input['recipient']));
	}
	$accepted = false;
	if (!empty($input['accepted'])) {
		$accepted = true;
	}
	$error = '';
	if (!empty($input['error'])) {
		$error = trim((string)$input['error']);
	}
	$message_id = '';
	if (!empty($input['message_id'])) {
		$message_id = trim((string)$input['message_id']);
	}

	if (!empty($recipient) && filter_var($recipient, FILTER_VALIDATE_EMAIL) === false) {
		$result['message'] = 'Recipient email is invalid.';
		return $result;
	}

	$error = preg_replace('/(password|token|secret|api[_-]?key)\s*[:=]\s*[^\s,&]+/i', '$1=[redacted]', $error);

	$status = 'failed';
	if ($accepted && empty($error)) {
		$status = 'accepted';
	}

	$result['success'] = true;
	$result['message'] = 'Email delivery result parsed.';
	$result['data'] = array(
		'provider' => $provider,
		'recipient' => $recipient,
		'status' => $status,
		'message_id' => $message_id,
		'error' => $error,
		'logged_at' => time()
	);

	return $result;
}