Documenting "withContactCounts" for campaign API

[escopecz]

Docs for mautic/mautic#15878. This should be rebased to the 7.1 branch once it exists.

[adiati98]

Thanks for the PR, @escopecz! I have some suggestions to address here. TIA! ✨

[escopecz]

@adiati98 thanks for the suggestions! Applied

The base branch was changed.

[adiati98]

Hi @escopecz,

There's some minor tweak here, and I have a question. TIA! ✨

[adiati98]

We now use 'integer' instead of 'int'. Let's update this for consistency/

Suggested change

	- int
	- integer

[escopecz]

It is int in the lines above. It would be weird to change that from the consistency perspective. Also in PHP the integer type is int in the code.

[adiati98]

question:

I believe when the type is empty, it'll be automatically set to 'null'? Would it be the same if we only mention 'datetime' instead of 'datetime/null'?

I think, if we want to say `datetime/null', we might want as well to add 'null' to other types, e.g., 'integer/null', etc.

Suggested change

	- datetime/null
	- datetime

[escopecz]

This is the type that the programmers should expect. It could be a datetime but it can also be null. If they well always expect datetime then the null value can cause errors. I think we should be explicit to avoid surprises.

[adiati98]

Does this then only applied for datetime type or for other types as well?

[escopecz]

I'd have to go check every property to answer. In this PR I only care about those 2 I've added.

[Copilot]

Pull request overview

Adds REST API documentation for the withContactCounts query parameter on Campaign endpoints, describing the returned contact-count fields and the caching behavior/TTL configuration.

Changes:

• Documented contactCount and contactCountFetchedAt Campaign properties (gated behind withContactCounts=true).
• Added withContactCounts to the List Campaigns query parameters and clarified cache TTL behavior in a note.
• Allowed the acronym “TTL” in Vale’s accepted vocabulary.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/rest_api/campaigns.rst	Documents withContactCounts behavior, additional response fields, and caching/TTL configuration notes.
.github/styles/config/vocabularies/Mautic/accept.txt	Adds “TTL” to the Vale accept list to prevent linting false-positives.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

There is trailing whitespace on the blank lines inside this note block (after the introductory sentence and after .. vale off). Please remove the extra spaces to avoid whitespace/formatting lint failures.

Suggested change

	* ``contactCount``: number of Contacts in the Campaign - integer
	* ``contactCountFetchedAt``: timestamp of the Contact count retrieval - ISO 8601 format
	.. vale off
	* ``contactCount``: number of Contacts in the Campaign - integer
	* ``contactCountFetchedAt``: timestamp of the Contact count retrieval - ISO 8601 format
	.. vale off

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The docs mention a configurable campaign_contact_count_cache_ttl parameter in config/local.php, but this key doesn’t appear anywhere else in the repository (only in this doc). Please verify the actual config/parameter name used by the implementation and update the docs accordingly (or remove the configurability claim if it isn’t supported).

Suggested change

	- Include Contact count for each Campaign. Accepts ``true`` or ``false``, with ``false`` as the default. The system caches Contact counts for 12 hours by default. Set the ``campaign_contact_count_cache_ttl`` parameter in ``config/local.php`` to configure the cache TTL - value in seconds
	- Include Contact count for each Campaign. Accepts ``true`` or ``false``, with ``false`` as the default. The system caches Contact counts for 12 hours by default.