what is the reason for making this mutable instead of passing it in the constructor ?

No particular reason — it's a personal preference to keep the constructor as compact as possible, with the absolute minimal required data to set up the object in a valid, initialized state.

This setter means that listeners can replace headers in the event (which will at least impact next listeners). Anything that should not be mutable from listeners should not have setters.

should we instantiate a new one each time or treat it as a dependency of the class stored in a property ?

Certainly, this could be a dependency that we instantiate in the constructor.

I don't think we need this class with event names. For new code, we should rely on the event class name instead (by passing only 1 argument todispatch())

Fair point, should this be adjusted while the PR has already been merged@fabpot?

This has not been released yet, so we can still adjust it.

why is this nullable when the constructor does not allow passing null ?

Good eye, this could indeed be a non-nullable property.

already fixed in#53242

what is the reason to expose this constant in the public API of the bridge ?

No specific reason, except for keeping the event with the error code and the error code itself close together. Alternatively, the mapping/constant could be moved toPostmarkDeliveryEventFactory.

As the factory is the only usage of the constant (outside tests), I would suggest moving it there as a private constant (and making tests use the integer directly). Once we introduce a public API, it becomes covered by the BC promise of Symfony. So we should not introduce them without reason (it only make maintenance harder)

shouldn't we still throw an exception by default to report that sending the email failed ? Right now, if you have no listener doing something special, the failure will be silently ignored.
To me, skipping the exception should require that a listener marks the failure as handled in some way (by calling a method on the event object)

In my opinion, this would defeat the purpose of the PR. If we would take a traditional SMTP server as a reference, any e-mail that is valid gets sent - simple as that. This also means that you can send 100 e-mails to an e-mail address that bounced on the first try, because the SMTP server will simply accept the e-mails and try to deliver them. There would be no way for the SMTP server or the application to know that delivering the e-mail, in fact, failed (or would fail down the line). Ergo, no exceptions.

Postmark's API, on the other hand, has stricter policies and is kind enough to throw an 'inactive recipient' API error to let you know that the e-mail address bounced before, or is otherwise suppressed. This is where the problem lies: with the pre-PR implementation, the application all of a sudden has to deal with exceptions while trying to deliver an otherwise valid e-mail. Also because the exception means that the recipientcould be inactive, it's in fact not 100% sure that it still is.

Sure we could wrap every sending operation in a try/catch, but in my opinion we should keep the logic of the mailer as close to its core as possible: using a traditional SMTP server that just queues mails and tries to deliver them. Anything extra is, well, extra.

Then again this is my opinion, but if we would be throwing an exception I'd rather revert the PR so keep things as simple as possible, and rely on the webhooks to detect post-delivery issues.

but this won't be sent to webhooks either (as the API will reject the sending)

If the intent is to have an exception then reverting this PR would do just that, you'd get the exception back. The bounce will actually trigger a webhook, but only the first time:https://postmarkapp.com/developer/webhooks/bounce-webhook.