Currently MailgunHandlerInterface::sendMail() specifies that a boolean should be returned to indicate whether the mail was sent successfully or not. The default implementation MailgunHandler::sendMail() catches any exception that occurs, logs it, and then returns FALSE.
This causes the cause of the error to be lost for the calling code. Depending on the actual error being thrown the calling code might need to take different actions. For example if a mail is rejected because it is sent through a sandbox test domain it should be dropped from the mail queue instead of being requeued.
It also looks like the default implementation does not respect the return type since it returns a \Prs\Http\Message\ResponseInterface on success instead of TRUE, but that is out of scope for this issue.
Don't catch the exception, but allow it to pass through, possibly wrapping it in a custom MailgunException runtime exception.
To retain backwards compatibility, we should introduce an optional flag $catch_exceptions = TRUE which can be deprecated to be removed in a next major version.
The signature of MailgunHandlerInterface::sendMail() changes to:
/**
* Connects to Mailgun API and sends out the email.
*
* @param array $mailgunMessage
* A message array, as described in
* https://documentation.mailgun.com/en/latest/api-sending.html#sending.
* @param bool $catch_exceptions
* Whether or not to catch exceptions. Defaults to TRUE. This parameter is
* deprecated and will be removed in Mailgun 2.x.
*
* @return bool
* TRUE if the mail was successfully accepted by the API, FALSE otherwise.
*
* @throws \Drupal\mailgun\Exception\MailgunException
* Thrown if the mail was not accepted by the API. This exception is only
* thrown if $catch_exceptions is FALSE.
*
* @see https://documentation.mailgun.com/en/latest/api-sending.html#sending
*/
public function sendMail(array $mailgunMessage, $catch_exceptions = TRUE);
Beautiful, modern php usage! Especially love the "fromException" method and the deprecation warning.
Approved in review :)