class MailgunDriver implements DriverInterface, HandlesWebhooks, ProvisionsWebhooks
Traits
Constants
| WEBHOOK_EVENTS |
Delivery-event webhook types Flarum registers with Mailgun. We only care about permanent (hard) failures and complaints; temporary failures are deliberately excluded so we never suppress over a transient problem. |
| MAX_WEBHOOK_URLS |
|
Methods
Returns a validation rule that checks for leading or trailing whitespace.
Ensure the given settings are enough to send emails.
Build a mail transport based on Flarum's current settings.
The Symfony request parser for this provider. The parser is fully responsible for **authenticating** the request and normalising the payload into a {\Symfony\Component\RemoteEvent\RemoteEvent}.
The secret passed to the parser's `parse()` call, if this provider uses one. Return null when the provider authenticates by other means (e.g.
Whether inbound webhooks can actually be received and trusted with the current settings. Drivers that require configuration the admin must supply (e.g. Mailgun's signing key) should return false until it is set, so the UI can warn that no bounces will arrive. Drivers that need no such config should simply return true. Shared provider IPs alone do not identify the account; Mailgun and Postmark require forum-specific credentials.
Whether this driver can report bounces at all with the current settings.
Whether a bounce or drop the parser reported is permanent. Flarum only flags the recipient when it is. Many providers report soft bounces as bounces too, so check the provider's own payload, available from $event->getPayload().
Register (or update) the delivery-event webhook with the provider, pointing it at the given Flarum webhook URL. Must be idempotent, and must keep any URLs other applications registered with the provider.
Remove the given Flarum webhook URL from the provider, leaving any other URLs in place. Should not throw if it is not registered.
The URLs that are not the given endpoint, whatever credentials either carries.
Details
in ValidatesMailSettings
at
line 19
protected callable
noWhitespace()
Returns a validation rule that checks for leading or trailing whitespace.
at
line 40
array
availableSettings()
Provide a list of settings for this driver.
The list must be an array of field names (keys) mapping to their type (the empty string "" for a text field; or an array of possible values for a dropdown field).
at
line 53
MessageBag
validate( SettingsRepositoryInterface $settings, Factory $validator)
Ensure the given settings are enough to send emails.
This method is responsible for determining whether the user-provided values stored in Flarum's settings are "valid" as far as a simple inspection of these values can determine it. Of course, this does not mean that the mail server or API will actually accept e.g. credentials. Any errors must be wrapped in a {\Illuminate\Support\MessageBag}. If there are no errors, an empty instance can be returned. In the presence of validation problems with the configured mail driver, Flarum will fall back to its no-op {\Flarum\Mail\NullDriver}.
at
line 62
bool
canSend()
Does this driver actually send out emails?
at
line 67
TransportInterface
buildTransport( SettingsRepositoryInterface $settings)
Build a mail transport based on Flarum's current settings.
at
line 79
RequestParserInterface
getWebhookRequestParser( SettingsRepositoryInterface $settings)
The Symfony request parser for this provider. The parser is fully responsible for **authenticating** the request and normalising the payload into a {\Symfony\Component\RemoteEvent\RemoteEvent}.
Verification is provider-specific and lives entirely in the parser — it may check an HMAC signature (Mailgun), an account-specific IP allowlist, or an SNS certificate (SES). Callers MUST NOT attempt to verify the request themselves; they should call {\Symfony\Component\Webhook\Client\RequestParserInterface::parse()} and treat a thrown {\Symfony\Component\Webhook\Exception\RejectWebhookException} as a rejection, and a `null` return as "verified but no actionable event" (e.g. an SES/SNS subscription-confirmation handshake).
at
line 87
string|null
getWebhookSigningSecret( SettingsRepositoryInterface $settings)
The secret passed to the parser's `parse()` call, if this provider uses one. Return null when the provider authenticates by other means (e.g.
an IP allowlist) — this is a valid, fully-supported state, NOT a misconfiguration. Providers that require a secret (e.g. Mailgun) must return false from webhookConfigured() while it is missing, so the request is refused before it reaches the parser.
at
line 92
bool
webhookConfigured( SettingsRepositoryInterface $settings)
Whether inbound webhooks can actually be received and trusted with the current settings. Drivers that require configuration the admin must supply (e.g. Mailgun's signing key) should return false until it is set, so the UI can warn that no bounces will arrive. Drivers that need no such config should simply return true. Shared provider IPs alone do not identify the account; Mailgun and Postmark require forum-specific credentials.
at
line 98
protected string|null
webhookCredentials( SettingsRepositoryInterface $settings)
at
line 108
bool
webhooksAvailable( SettingsRepositoryInterface $settings)
Whether this driver can report bounces at all with the current settings.
Return false for a configuration that never delivers mail to real recipients, such as a sandbox mode, and Flarum hides bounce handling entirely instead of warning that it is not set up.
at
line 113
bool
isPermanentFailure( MailerDeliveryEvent $event)
Whether a bounce or drop the parser reported is permanent. Flarum only flags the recipient when it is. Many providers report soft bounces as bounces too, so check the provider's own payload, available from $event->getPayload().
at
line 121
void
registerWebhook( SettingsRepositoryInterface $settings, string $url)
Register (or update) the delivery-event webhook with the provider, pointing it at the given Flarum webhook URL. Must be idempotent, and must keep any URLs other applications registered with the provider.
at
line 159
void
unregisterWebhook( SettingsRepositoryInterface $settings, string $url)
Remove the given Flarum webhook URL from the provider, leaving any other URLs in place. Should not throw if it is not registered.
at
line 187
protected array
withoutEndpoint(array $urls, string $url)
The URLs that are not the given endpoint, whatever credentials either carries.