- How do I install dyaskur/sendfox-php in a Laravel application?
- Install it with Composer using composer require dyaskur/sendfox-php. Laravel's package auto-discovery registers the service provider, which adds the sendfox mailer and the webhook route. Publish the package config, then set your SendFox API key (for example SENDFOX_API_KEY) in the environment file. Keep the mailer name and webhook path configurable so you can change them without touching application code.
- Can I send Laravel Mailables and notifications through SendFox with this package?
- Yes. The package provides a Symfony Mailer TransportInterface plus a Laravel service provider that registers an auto-discovered sendfox mailer. Anything that goes through Mail, Mailable or Notifiable works, so integration is mostly configuration: mailer entry, credentials and driver selection. You can set it as the default mailer or select it per message with Mail::mailer('sendfox').
- Can I use dyaskur/sendfox-php without Laravel, in plain PHP or Symfony?
- Yes, the API client is framework-agnostic and has minimal dependencies, so it installs cleanly into any Composer project. You instantiate it directly, for example new SendFox($key, maxRetries: 5), and call the fluent methods for contacts, lists and campaigns. It uses a PSR-compatible HTTP transport, so you can inject your own PSR-18 client for logging, proxies or custom timeouts.
- How does the package handle pagination when listing contacts and campaigns?
- Version 0.3.0 added cursor-style pagination on the API client, exposed through a paginate() helper. That lets you iterate large contact and list collections without manually tracking cursors or page numbers in your own sync jobs. It also makes the package practical for audience sync work, not just for sending mail. Check the response objects for the cursor and remaining-items metadata if you need to resume a job later.
- How are SendFox webhooks verified, and do they add operational work?
- The service provider registers POST /sendfox/webhook and dispatches a WebhookReceived event. Verification computes an HMAC over the raw request body and compares it to X-SendFox-Signature, plus a plus-or-minus five minute timestamp window and per-event-ID suppression of provider retries. The remaining work is yours: choose a route prefix, middleware, CSRF exemption and throttling, and back the dedupe store with something durable and safe across multiple app instances. Budget a few days including tests, not hours, and manage secret rotation.
- What is the retry behaviour for 429 and 5xx responses from SendFox?
- A 429 that includes a Retry-After header is honoured, and 5xx and network errors are retried on idempotent methods. The retry count is tunable through the maxRetries constructor argument and retries can be disabled entirely. A 429 without Retry-After usually means monthly quota is exhausted, and that case fails fast rather than retrying. Remember that package retries sit underneath Laravel queue retries, so reason about the total retry budget end to end to avoid amplification and unpredictable delivery latency.
- How should I set the Idempotency-Key so retries don't double-send email?
- The mail transport propagates an Idempotency-Key header, which turns at-least-once queue semantics into effectively-once delivery for the provider. The key must be deterministic per logical message, for example derived from the Mailable class plus a business key such as an order ID. A random UUID generated per attempt gets the API call but not the guarantee, because each retry looks like a new message. Generate the key where the job is dispatched, not inside the transport.
- Which PHP and Laravel versions does dyaskur/sendfox-php support, and how stable is it?
- The core is framework-agnostic and the Laravel integration is registered through package auto-discovery. Because the package is pre-1.0 with several minor releases and no stated deprecation policy, check composer.json for the exact PHP and illuminate/support constraints before upgrading. Pin an exact version in composer.json and keep the mailer name and webhook path behind config so a constructor or route change is a one-line fix.
- How do I test my SendFox integration without calling the real API?
- Swap the PSR-compatible HTTP client for a mock such as Guzzle's MockHandler or a PSR-18 test double, then assert on request paths, bodies and headers, including the Idempotency-Key. For webhooks, build payloads with a computed HMAC signature and a fresh timestamp, and verify that replayed event IDs are suppressed by your dedupe store. Also test the 429 and 5xx paths to confirm retry limits and that quota failures surface as hard errors. Laravel's HTTP fakes and Mail fakes cover the application-level wiring.
- How does this compare to calling the SendFox API directly with Guzzle?
- A hand-rolled Guzzle client gives you full control but you would reimplement authentication, error mapping, pagination, retries and Idempotency-Key propagation yourself. This package wraps those concerns behind a fluent, object-oriented API and adds a Symfony mail transport plus a Laravel service provider, which is the main reason to choose it over raw HTTP calls. If you only need one or two endpoints and no mail sending, a small custom client may be simpler. If you want Mail, Notifiable and contact sync in one dependency, the package saves meaningful boilerplate.