getbrevo/brevo-php v5.0.0-rc.1 on GitHub

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.