Mailjet Laravel Package

Getting Started

splash/mailjet is not a Mailjet SDK wrapper you reach for when you want to send transactional email. It is a SplashSync connector bundle: a thin, opinionated adapter that maps Splash objects (ThirdParties, Addresses, etc.) onto Mailjet contacts and lists, and is designed to be embedded inside the SplashSync server rather than bootstrapped in a normal Laravel app. Treat it as infrastructure for a Splash deployment, not a general-purpose library.

Minimal steps:

1. Install it as a Splash connector dependency — it expects splash/php-core (or the Splash framework packages) to already be present and will pull its own mailjet/apiv3-style client. Do not try to composer require it into a bare Laravel skeleton and expect service providers to resolve.
2. Register the bundle in the Splash kernel's bundle list (typically config/bundles.php when running under a Symfony-flavoured Splash host). The bundle class lives at the package root under Splash\Bundle\MailjetBundle.
3. Open the connector settings form (Form/ConnectorSettingsType or similar) from the Splash back-office, and paste your Mailjet API Key and API Secret. These are stored by Splash's ConfigurationService, not in .env — a common source of confusion.
4. Where to look first, in order: the bundle class → Resources/config/services.yaml (to see which services are wired) → the Services/ directory (the actual object mapping) → Form/ for the credential fields.
5. First real use case: connect a Splash instance to a Mailjet account and push ThirdParty records into a Mailjet contact list, then verify contact creation in the Mailjet dashboard. If that round-trip works, everything else is variations on the same service pattern.

Implementation Patterns

Service-per-object mapping. Splash connectors implement a fixed set of interfaces per object type — CrudServiceInterface, PrimaryServiceInterface, ListServiceInterface, ObjectServiceInterface. Each Mailjet resource you want to expose gets its own service class wired in services.yaml and tagged so Splash's service locator can find it. Adding a new object type is a matter of copying an existing service, changing the getType()/getObjectClass() methods, and tagging it.

The commit lifecycle is the workflow. You never call this package directly from a controller. Splash's sync engine invokes your service's create(), update(), delete() and commit() methods in response to upstream changes. commit() is where the actual Mailjet HTTP call happens — the create/update methods only populate an in-memory object. Keep them side-effect free; that separation is what makes Splash retries safe.

Settings, not config files. Connector parameters (API keys, default list ID, sandbox flag) are read via the injected configuration service at call time:

$apiKey = $this->configuration->getParameter('MAILJET_APIKEY');
$listId = $this->configuration->getParameter('MAILJET_LIST');

Because these are resolved per-request rather than baked at container compile time, you can point a single Splash instance at different Mailjet accounts per connector configuration — useful for multi-tenant or staging/prod splits.

Integration tip: Mailjet contacts are keyed by email, and Splash's ThirdParty primary key is usually an internal ID. Implement getPrimaryKey() in terms of the email field and let a separate AddressService handle the Properties payload. Trying to use the internal ID as the Mailjet contact ID will cause duplicate contacts on the next sync.

Testing. Use Splash's own test toolkit rather than raw PHPUnit against the Mailjet client; the connector services assume an initialized Splash context. Mock at the HTTP client boundary and assert on the outbound payload shape.

Gotchas and Tips

• Zero stars, zero dependents. There is no community, no issue history to mine, and no blog posts. Budget time to read the source. Assume the README is a stub — do not trust it over the code.
• "Embedded" means no Laravel auto-discovery. There is no extra.laravel.providers. If you are trying to use this in a plain Laravel app, you are on the wrong package — you want a Mailjet API client plus your own sync logic.
• Version pinning is brittle. Splash bundles are split out of a monorepo and their composer.json constraints on splash/php-core move fast. Lock the Connector and Core versions together and expect to bump both simultaneously.
• Rate limits are real. Mailjet throttles aggressively on /contact and /contactdata writes. Splash will happily queue hundreds of commits; if your services fire one HTTP call per commit, a bulk import will 429. Batch inside commit() where the object type allows it, and log throttled responses rather than throwing — Splash retries on exception and will amplify the problem.
• Custom fields must pre-exist in Mailjet. Writing Properties to an undeclared Mailjet contact property returns a 400 that surfaces as a generic Splash commit error. Create the MailjetContactProperty definitions first (or add them to your connector's install/verify step) and map names exactly — Mailjet is case-sensitive on property names.
• Debugging: Splash's own logger is the primary signal, not Mailjet's dashboard. Turn the connector log level to debug, then inspect the raw request/response trace — the service layer swallows HTTP status text into Splash's SyncException message. If you see nothing at all, the service tag is missing from services.yaml, not a credential problem.
• Extension points: the cleanest way to customise behaviour is to override a service definition in your host app's services.yaml (same service ID, your class) rather than forking the bundle. Forking is an option — the bundle is small — but you will lose every upstream fix, and given the near-zero activity you should assume there will be very few, so a local fork is a defensible choice here.
• Sandbox flag: if a sandbox/test connector parameter exists, verify it actually routes to Mailjet's sandbox endpoint. Broken sandbox toggles are common in low-activity connectors, and the failure mode is silently mutating production contacts.