<?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\EntityMutableInterface;
use KTXF\Mail\Exception\SendException;

/**
 * Mail Service Transmit Interface
 * 
 * Interface for mail services capable of transmitting outbound entities.
 * 
 * @since 2025.05.01
 */
interface ServiceEntityTransmitInterface extends ServiceBaseInterface {

    public const CAPABILITY_ENTITY_TRANSMIT = 'EntityTransmit';

    /**
     * Creates a fresh entity instance for composition
     *
     * @since 2025.05.01
     *
     * @return EntityMutableInterface Fresh entity object
     */
    public function entityFresh(): EntityMutableInterface;

    /**
     * Transmits an outbound entity
     *
     * @since 2025.05.01
     *
     * @param EntityMutableInterface $entity Entity to transmit
     *
     * @return string Entity identifier assigned by the transport
     * 
     * @throws SendException On delivery failure
     */
    public function entitySend(EntityMutableInterface $entity): string;

}