Skip to content

Documenting "withContactCounts" for campaign API #293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
escopecz wants to merge 12 commits into
base: 7.1
Choose a base branch
from
Open

Documenting "withContactCounts" for campaign API #293

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2cbb1f7
Documenting "withContactCounts" for campaign API
escopecz Feb 17, 2026
a46e7b5
Apply suggestions from code review
escopecz Feb 18, 2026
4c3004b
add TTL to accept.txt and remove excess period
adiati98 Feb 18, 2026
c40d7c3
Merge branch '5.x' into MAUT_13385
adiati98 Feb 27, 2026
c3e09a6
Merge branch '5.x' into MAUT_13385
adiati98 Mar 4, 2026
2458a9b
Merge branch '5.x' into MAUT_13385
adiati98 Mar 5, 2026
6e7abdb
Merge branch '5.x' into MAUT_13385
adiati98 Mar 8, 2026
d39dc2d
Merge branch '5.x' into MAUT_13385
adiati98 Mar 24, 2026
62c5ae2
Merge branch '7.1' into MAUT_13385
adiati98 Mar 25, 2026
b154c3d
Capital C
escopecz Mar 25, 2026
9dfe3e7
Update docs/rest_api/campaigns.rst
escopecz Mar 25, 2026
96d6268
Merge branch '7.1' into MAUT_13385
adiati98 Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/styles/config/vocabularies/Mautic/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ Transifex
Translator
TRUE
true
TTL
Twilio
unassign
unpublish
Expand Down
21 changes: 21 additions & 0 deletions docs/rest_api/campaigns.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,12 @@
* - ``events``
- array
- Array of Event entities for the Campaign - see below
* - ``contactCount``
- int
Comment thread
RCheesley marked this conversation as resolved.
- Number of Contacts in the Campaign. This property is only returned by endpoints that support the ``withContactCounts=true`` query parameter (for example, ``GET /campaigns``) and is not available from ``GET /campaigns/{id}``

Check warning on line 155 in docs/rest_api/campaigns.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Contractions] Feel free to use 'isn't' instead of 'is not'.

Raw Output:
{"message": "[Google.Contractions] Feel free to use 'isn't' instead of 'is not'.", "location": {"path": "docs/rest_api/campaigns.rst", "range": {"start": {"line": 155, "column": 186}}}, "severity": "INFO"}

Check warning on line 155 in docs/rest_api/campaigns.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/rest_api/campaigns.rst", "range": {"start": {"line": 155, "column": 3}}}, "severity": "INFO"}
* - ``contactCountFetchedAt``
- datetime/null
Copy link
Copy Markdown
Contributor

@adiati98 adiati98 Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@escopecz escopecz Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

@adiati98 adiati98 Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member Author

@escopecz escopecz Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- Timestamp of the Contact count retrieval. This property is only returned by endpoints that support the ``withContactCounts=true`` query parameter (for example, ``GET /campaigns``) and is not available from ``GET /campaigns/{id}``

Check warning on line 158 in docs/rest_api/campaigns.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Contractions] Feel free to use 'isn't' instead of 'is not'.

Raw Output:
{"message": "[Google.Contractions] Feel free to use 'isn't' instead of 'is not'.", "location": {"path": "docs/rest_api/campaigns.rst", "range": {"start": {"line": 158, "column": 192}}}, "severity": "INFO"}

Check warning on line 158 in docs/rest_api/campaigns.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "docs/rest_api/campaigns.rst", "range": {"start": {"line": 158, "column": 3}}}, "severity": "INFO"}


**Event Properties**
Expand Down Expand Up @@ -246,6 +252,8 @@
- Only return currently published entities
* - ``minimal``
- Return only array of entities without additional lists in it
* - ``withContactCounts``
- 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
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.


**Response**
Expand Down Expand Up @@ -313,6 +321,19 @@
}
}

.. note::

The ``withContactCounts=true`` parameter adds two additional fields per Campaign:

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

.. vale off

Comment on lines +327 to +332
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
The system caches Contact counts for 12 hours by default to improve performance. New Contacts added to Campaigns may not appear until the cache expires. Set the ``campaign_contact_count_cache_ttl`` parameter in ``config/local.php`` to configure the cache TTL - value in seconds.

.. vale on

**Properties**

Same as `Get Campaign <#get-campaign>`_.
Expand Down
Loading