<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Mail\Service;

use KTXF\Mail\Entity\IMessageMutable;
use KTXF\Mail\Exception\SendException;

/**
 * Mail Service Send Interface
 * 
 * Interface for mail services capable of sending outbound messages.
 * This is the minimum capability for an outbound-only mail service.
 * 
 * @since 2025.05.01
 */
interface ServiceMessageSendInterface extends ServiceBaseInterface {

    public const CAPABILITY_SEND = 'Send';

    /**
     * Creates a new fresh message object
     *
     * @since 2025.05.01
     *
     * @return IMessageMutable Fresh message object for composing
     */
    public function messageFresh(): IMessageMutable;

    /**
     * Sends an outbound message
     *
     * @since 2025.05.01
     *
     * @param IMessageMutable $message Message to send
     *
     * @return string Message ID assigned by the transport
     * 
     * @throws SendException On delivery failure
     */
    public function messageSend(IMessageMutable $message): string;

}