- How do I install emailsherlock/email-guard-core in a Laravel app?
- Run composer require emailsherlock/email-guard-core from your Laravel project root; it requires PHP 8.1 or newer and has no framework dependency. There is no published service provider or facade, so installation is just the Composer package plus whatever thin wrapper you write. You can then instantiate EmailGuard directly in a controller, a queued job, or a custom validation rule. Most teams add a small config/email-guard.php and a provider that binds a configured EmailGuard instance into the container.
- Does this package ship a Laravel service provider or validation rule?
- No. The library is deliberately framework-agnostic: it exposes a single EmailGuard entry point that returns a Result object with a verdict, an action, and a reasons collection. Laravel integration means writing a first-party wrapper: a config file, a provider that binds EmailGuard with config-derived options, and a Rule object mapping Deny to a validation failure. That is roughly half a day of work for a mid-level engineer because the surface area is one method, but you own the wiring.
- What does email-guard-core check without an API key?
- With no api_key set, the guard performs fully offline checks: broken syntax, reserved TLDs such as .invalid used by deleted accounts, and 73,000+ known disposable domains from a bundled snapshot. There are zero network calls, so latency is effectively nil and no email address leaves your infrastructure. This makes it safe to adopt without a vendor contract, a DPA, or a privacy review on day one.
- How do I enable the EmailSherlock Verify API escalation?
- Pass an api_key in the constructor options; a null key disables the remote check entirely. Escalation is policy-driven through block_on and review_on, so you decide which verdicts deny and which flag for a second gate. The API adds live MX records, an SMTP probe, a fresher disposable list, and role and catch-all detection. Remember that enabling it sends the email address to a third party, so document a lawful basis before using it in EU-facing signup flows.
- What is the difference between the Allow, Deny and Review actions?
- Action is resolved from your policy rather than being a raw boolean. Allow means the address passed, Deny means it matched a verdict in block_on, and Review means it matched review_on and should be held for a second gate. Review maps cleanly to a confirm-your-email flow for catch-all domains and role accounts instead of forcing a hard rejection into the validation layer. Each result also carries a reasons array of machine-readable codes such as reserved_tld or mailbox_not_found.
- Which PHP and Laravel versions does email-guard-core support?
- The package requires PHP 8.1 or newer and declares no Laravel dependency, since it is pure PHP with no HTTP kernel coupling and no global state. In practice that means it works in any Laravel version running PHP 8.1+, but Laravel support is not officially declared, so treat framework compatibility as your wrapper's responsibility. Check the repository and Packagist entry for the current constraint before pinning.
- How do I stop an API outage from blocking legitimate signups?
- The fail_open option defaults to true, meaning an EmailSherlock outage lets addresses through rather than blocking them. Set timeout_ms (default 800) to cap the total budget for the API call so a slow remote response never stalls your signup or checkout path. When the API was wanted but unreachable, the Result sets degraded to true, which you can log or alert on. Combined with local checks still running first, this keeps the hot path resilient.
- Can I write tests for this email guard without hitting the network?
- Yes. With api_key left null the guard performs only local checks and makes no network calls, so your unit and feature tests stay deterministic and fast. Assert on the action and reasons fields rather than on a single boolean, since reasons carry the machine-readable codes. If you need to test escalation behavior, mock the HTTP layer inside your own wrapper rather than in the library, or inject a fake result.
- Is emailsherlock/email-guard-core safe to run in production?
- Treat it as a candidate, not a commitment. Maturity signals are weak: zero stars, zero dependents, a single maintainer, and a release tagged with a future date that should be reconciled against the commit SHA and Packagist entry before you trust it. The bundled 73k disposable-domain snapshot only stays useful if it is refreshed, since disposable domains rotate quickly and a stale list silently degrades to allow. Recommended precautions are pinning by SHA, reviewing the transitive dependency graph, and keeping aggressive block_on values such as catch_all or role off until you have measured conversion impact.
- What are the alternatives to email-guard-core for Laravel email validation?
- You can combine Laravel's built-in email and dns validation rules with a disposable-domain blocklist package, or call a commercial verification API directly from a custom rule. The case for this library is the offline-first split: deterministic local checks catch malformed addresses, reserved TLDs and known disposables at zero latency, with remote MX, SMTP and catch-all detection as opt-in escalation. The tradeoff is that you write and maintain the Laravel adapter yourself, and an official adapter could later land with a different config schema, creating a small migration liability.