[Mailer] Return SentMessage from Mailer::send if available

[pableu]

Q	A
Branch?	5.x
Bug fix?	no
New feature?	yes
Deprecations?	no
Tickets	#35670
License	MIT
Doc PR	Coming Soon :-)

Since #36424, you can get the SentMessage if sending was handled by the messenger. But there's no easy and developer friendly way to do it without messenger.

This has been discussed a few times already (threads in #35670, #33681, #35670), but none of these discussions have resulted in a solution with good DX.

The SentMessage helps you get the Messge-ID, which some transports (such as Amazon SES) set by themselves. That might be useful as proof-of-delivery or when building something like a ticketing system (for matching replies using In-Reply-To and References headers).

I think returning SentMessage here is dev-friendly and pragmatic: If we have it, we return it. If we don't have it, we return null.

[Nyholm]

Thank you. This PR cannot be merge since it contains a BC break.

Just a question, why don't you use TransportInterface directly in your code?

[Nyholm]

This is a BC break and must be reverted. :/

[pableu]

I was afraid that this is a BC break. Could we target that for Symfony 6? :)

Could I add an additional method to MailerInterface? Like.. MailerInterface::getLastSentMessage? That would work for me but doesn't feel right.

why don't you use TransportInterface directly in your code?

That's a possible solution, but then I have to build more code around it than I'd like. I think returning the SentMessage if available would give a better DX.

[Nyholm]

Could I add an additional method to MailerInterface?

Im sorry, no. See https://symfony.com/doc/current/contributing/code/bc.html

why don't you use TransportInterface directly in your code?

That's a possible solution, but then I have to build more code around it than I'd like. I think returning the SentMessage if available would give a better DX.

I dont understand what you mean with "more code around it".

I assume that you have a class like this (that uses your patch):

class WelcomeEmailSender
{
    private MailerInterface $mailer;

    private function sendWelcome() {
        $message = new RawMessage(/**/);
        $sentMessage = $this->mailer->send($message);

        // Or store it in a log file. 
        echo $sentMessage->getMessageId();
    }
}

Isn't just to do this and you are all done:

-    private MailerInterface $mailer;
+    private TransportInterface $mailer;

[pableu]

Oh, you're right, I see! I didn't realize that I can also get the TransportInterface through DI. That works fine for my use-case.

Thanks a lot @Nyholm, sorry for abusing this PR for support.