getbrevo/brevo-php

v5.0.0-rc.1

Release candidate for the v5 line. This pre-release is published so adopters can validate the new surface against their integrations before v5.0.0 is tagged stable. It is not picked up by composer update automatically — opt in explicitly (see Installing this RC below).

If no blocking issues surface within the soak window, this build will be promoted to v5.0.0 unchanged.

composer require getbrevo/brevo-php:^5.0.0@RC

Status

• Stability: RC — API surface is frozen. Only critical regressions discovered during soak will be patched into an RC.2.
• v4.x: remains supported and continues to receive wire-compatibility fixes.
• Feedback welcome: please open an issue against getbrevo/brevo-php if you hit anything unexpected during migration. Tag with v5-rc.

Why this release

Most of the breaking changes in v5 come from an internal effort at Brevo to make our API endpoints, parameters and models more self-descriptive. The goal is to make the public surface easier to read at a glance — both for developers and for AI agents working against the Brevo API — so that names, shapes and required fields convey intent without needing to cross-reference external docs. Concretely, this means consistent parameter naming, payload wrappers that reflect what the endpoint actually does (e.g. CreateBatchEventsRequest), filter keys that match the wire format, model fields renamed or removed where the previous names were ambiguous, and tightened types (DateTime instead of string for dates, typed unions instead of generic arrays) so static analysis catches mistakes earlier.

We're aware that renaming costs callers a one-time migration, and we've kept v4.x supported so you can adopt v5 on your own timeline.

⚠️ Breaking changes

Companies — GetCompaniesRequest::filters renamed

• filters is renamed to filtersAttributesName to match the wire format.
• Existing code passing 'filters' => ... does not throw, but the filter is silently ignored server-side and the response is unfiltered. Audit every call site.

Events — Event::createBatchEvents payload shape changed

• First argument changed from array to a CreateBatchEventsRequest wrapper.

Balance — getActiveBalancesApi response shape changed

• Return type changed from ?BalanceLimit to ?GetLoyaltyBalanceProgramsPidActiveBalanceResponse (different shape).

Balance — getContactBalances requires balanceDefinitionId

• $request no longer defaults to empty; balanceDefinitionId is required.

Balance — BeginTransactionRequest::eventTime type tightened

• Type changed from ?string to ?DateTime. ISO strings now cause TypeError.

CRM — Tasks::getAllTaskTypes returns an array

• Return type changed from ?GetCrmTasktypesResponse (wrapper) to ?array<GetCrmTasktypesResponseItem>.

Email campaigns — utmIdActive renamed

• EmailCampaigns\GetEmailCampaignResponse::utmIdActive renamed to utmId (wire key utmIDActive → utmID, type ?bool → ?int).
• Same change on GetEmailCampaignsResponseCampaignsItem.

Model fields removed

• GetAccountResponse::dateTimePreferences
• Webhook::channel
• GetProcessResponseInfo::export
• GetProcessResponse::error, ::createdAt, ::completedAt
• Several ExternalFeeds response fields

Model field types tightened

• Process\GetProcessResponseInfoImport count fields changed from ?int to ?string (now URLs to CSV reports) — affects invalidEmails, duplicateContactId, duplicateExtId, and others.
• Ecommerce\CreateUpdateProductResponse::id and CreateUpdateCategoryResponse::id: ?int → ?string.
• Several string date fields tightened to ?DateTime (Program::*, Reward::*, BalanceLimit::createdAt/updatedAt).

Model fields renamed

• ConversationsMessageAttachmentsItem::fileName → name, ::inlineId → link.

Custom objects — associations union flattened

• UpsertrecordsRequestRecordsItemAssociationsItem is now a single class with an action: 'link' | 'unlink' discriminator. 7 old variant classes have been deleted.

Added

• New optional fields and filters across contacts->createContact, contacts->updateContact, emailCampaigns->getEmailCampaigns, ecommerce->getProducts, and several other endpoints.
• Tier groups support upgrade and downgrade schedule fields.

Installing this RC

Composer only installs RC builds when you ask for them explicitly. Either:

composer require getbrevo/brevo-php:^5.0.0@RC

Or set minimum-stability in your composer.json:

{
  "minimum-stability": "RC",
  "prefer-stable": true,
  "require": {
    "getbrevo/brevo-php": "^5.0"
  }
}

When v5.0.0 ships stable, composer update will swap this RC for the stable release automatically.

Holding on v4.x

If you're not ready to migrate, pin to v4:

composer require getbrevo/brevo-php:^4.0

Migration

See the Upgrading from v4.x guide for full migration details.

Documentation

• PHP SDK guide
• Full changelog
• API reference

Fixed

• CreateBatchOrderResponse::$batchId now deserializes correctly. The createBatchOrder endpoint returns the batch id as batch_id (snake_case), but the SDK looked for batchId, leaving it unset and throwing Cannot assign null to property ...::$batchId of type float on every call. The wire mapping is corrected to batch_id and the property is now nullable (?float). The $response->batchId accessor is unchanged.

Backward-compatible patch release. No breaking changes.

Fixed

• GetCampaignStats count fields are now nullable (?int): clickers, complaints, delivered, hardBounces, sent, softBounces, trackableViews, uniqueClicks, uniqueViews, unsubscriptions, viewed. This model is reused for statsByDomain on getEmailCampaign(s), where per-domain rows are sparse and the API returns null/absent for some counts. The previous non-nullable typing threw a TypeError while deserializing statsByDomain (globalStats was unaffected). (#138)

Backward-compatible patch release. No breaking changes.

Fixed

• senderEmail is now nullable (?string) on GetTransacBlockedContactsResponseContactsItem; the API returns null for some blocked or unsubscribed contacts (#137)
• campaignId is now nullable (?int) on both UserUnsubscription item classes; form based unsubscriptions return null (#136)
• Guzzle timeout support now works: interface_exists replaces class_exists for GuzzleHttp\ClientInterface, so the timeout option is honored (#133)

Backward compatible patch release. No breaking changes.

v4.0.13

Bug fixes

getProcess / getProcesses — deserialization failure on completed processes (#121)

• $duplicateEmailId was typed as ?int, but the API returns a URL string pointing to a CSV file of duplicate IDs.
• It is now typed as ?string.

getProcess / getProcesses — unknown status in_process (#122)

• The API still returns the legacy in_process value (v3 name for processing).
• GetProcessResponseStatus and GetProcessesResponseProcessesItemStatus now include InProcess = "in_process", so deserialization no longer throws on active processes.

createEvent / createBatchEvents — boolean values rejected in contactProperties (#123)

• contactProperties and eventProperties only accepted string|int.
• Boolean values (e.g. 'MY_FLAG' => true) now serialize correctly.

createContact / updateContact — integer values rejected in attributes (#124)

• attributes values were typed as float|string|bool|array.
• Passing a plain PHP int (e.g. 'OFFICE_ID' => 1234) now works without casting to (float).

Summary

Resolved a field naming mismatch in the /orders/status/batch API response to align the implementation with the public contract.

Issue

During investigation of an L3 issue, a discrepancy was identified between the Swagger contract and the actual API response:
• Contract (Swagger): batchId (camelCase)
• Implementation: batch_id (snake_case)

This inconsistency caused misalignment with client expectations and SDK behavior.

Fix
• Updated the response format to use batchId (camelCase) as defined in the Swagger specification.
• Ensured consistency across API responses and documentation.

What's Changed

New features

Events

• Added getEvents() — retrieve a paginated list of custom events, filterable by contactId, eventName, objectType, startDate, and endDate.
  Supports limit (default 100, max 10,000) and offset for pagination.
  Note: currently only supports custom events.
• Added createBatchEvents() — create multiple events in a single request using an array of CreateBatchEventsRequestItem. Returns a BatchAcceptedResponse.

Ecommerce

• CreateUpdateProductRequest and batch product upsert now accept two new optional fields: brand and description.

Balance

• getActiveBalancesApi() now accepts includeInternal to include balances tied to internal definitions.
• getContactBalances() and getSubscriptionBalances() now accept a request object with an includeInternal parameter.
• getTransactionHistory() now supports filtering by status (draft, completed, rejected, cancelled, expired) and transactionType (credit, debit).
• createBalanceDefinition() and updateBalanceDefinition():
  • the meta field is now a typed object (isInternal: bool) instead of a generic key-value array.

CRM

• Added PatchCrmAttributesIdRequest to update CRM attribute labels and selectable option labels.

Changes

Ecommerce

• metaInfo size limit for products clarified: maximum 20,000 characters total (previously documented as 1,000 KB / max 20 items).

Account

• users field on plan verticals is now nullable.

Bug fixes

• createContact() no longer throws a BrevoException
• Checks if the response body is empty and returns null instead of trying to deserialize it
• Only calls CreateContactResponse::fromJson($json) when there's actual content

• chore: update Fern CLI version to 3.85.3
• Update the Fern CLI version from 3.82.0 to 3.85.3 to incorporate latest tooling improvements and bug fixes.
• Key changes:
• Update cliVersion in .fern/metadata.json from 3.82.0 to 3.85.3
• Maintain existing generator configuration settings
• 🌿 Generated with Fern