| name | mautic-usage |
| description | Work with a Mautic marketing automation instance from the command line — look up contacts and their activity, manage segments, campaigns, forms and emails, send email, query page-hit and email statistics, and switch between Mautic instances with named profiles. Use when someone asks about Mautic contacts, leads, segments, campaigns, landing pages, email performance, form submissions, or marketing automation data. |
| license | MIT |
| compatibility | Requires the `mautic` binary on PATH — run the mautic-install skill if it is missing — and credentials for a Mautic instance, either MAUTIC_BASE_URL plus MAUTIC_API_USER and MAUTIC_API_KEY, or a profile configured with `mautic configure`. |
| allowed-tools | Bash(mautic:*) Bash(jq:*) Bash(command:*) Read Write |
Working with Mautic
mautic wraps the Mautic REST API. This skill is the procedure; the complete
reference is in the binary, via mautic llm.
1. Confirm the tool and the credentials
command -v mautic && mautic auth status --verify
command not found → run the mautic-install skill.credentials: NOT USABLE → the output names exactly what is missing. Ask the
user for the Mautic instance URL, an API user and its password, then either
export MAUTIC_BASE_URL, MAUTIC_API_USER and MAUTIC_API_KEY, or run
mautic configure --url … --username … --password ….HTTP 401 or 403 → the credentials are wrong, or Mautic's API is switched
off (Configuration → API Settings), or the user's role lacks the permission.
Never echo a password or token back into the conversation. Read the value
from the environment; do not print it.
The status output names the instance and the identity. Check it before any
write — a Mautic instance usually holds real customer data, and several
instances usually look alike.
2. Before writing anything
Writes here reach real people and some are irreversible. In order:
| Command | What it actually does |
|---|
mautic emails send <id> | mails every contact in the email's segments. Cannot be recalled |
mautic contacts batch delete --id … | permanent |
mautic contacts dnc remove <id> email | reverses a consent decision the contact made |
mautic <resource> update <id> --replace | PUT: blanks every field you did not pass |
mautic fields delete <id> | drops the column and every value in it |
Everything that writes accepts --dry-run, which prints the exact request and
sends nothing, and refuses to run without --yes. Use both:
mautic emails send 42 --dry-run
mautic emails send 42 --yes
Report what a dry run would do and let the user decide. Do not pass --yes on
their behalf unless they asked for the action itself.
3. Pick the command by the question
| The user asks | Command |
|---|
| "how many contacts do we have?" | mautic contacts list --limit 1 --format json — read total, not count |
| "find this person" | mautic contacts list --search 'email:someone@example.com' --format json |
| "what has this person done?" | mautic contacts activity <id> --limit 20 |
| "which segments is this contact in?" | mautic contacts segments <id> |
| "what pages got traffic yesterday?" | mautic stats query page_hits --where date_hit:gte:<date> --order date_hit:desc --all --format csv |
| "how did that email do?" | mautic data get emails.in.time --date-from … --date-to … --time-unit d --dataset sent --dataset opened |
| "list our segments / campaigns / forms" | mautic segments list · mautic campaigns list · mautic forms list |
| "add this person to a segment" | mautic segments add-contact <segment-id> <contact-id> |
| "who submitted this form?" | mautic forms submissions <form-id> |
| "stop emailing them" | mautic contacts dnc add <id> email |
| "what fields can I set?" | mautic fields list |
| something not listed here | mautic api GET /some/path |
Field aliases are configured per instance. Run mautic fields list before
writing contact data — Mautic ignores properties it does not recognise, so a
wrong alias looks like a successful write.
4. Read only the reference you need
The command catalog is long. Take a slice:
mautic llm | sed -n '1,/^# Pitfalls/p'
mautic llm --format json | jq -r '.[] | select(.file=="20-analytics.md") | .body'
mautic contacts list --help
5. Run it, and interpret the output honestly
- Parse
--format json, jsonl or csv. Never the table — it truncates
cells and shows a curated subset of columns.
total is not count. --format json returns
{"total":N,"count":M,"items":[…]}; the default page is 30 records. Say "the
first 30 of 4,318" rather than "4,318" when you only fetched 30. Use --all
to page through everything.- Most contacts are anonymous visitors with no email or name. Filter with
--where email:isNotNull before reporting on "contacts".
--order-by and --where take database columns in snake_case —
date_identified, not dateIdentified. A wrong column is ignored silently
and the rows come back in some other order.- Stats timestamps are UTC, while entity dates use the instance's timezone.
When a daily figure is off by one day, this is why.
- A batch 200 is not per-record success. Check
statusCodes in the
response.
Failure modes
| Symptom | Fix |
|---|
command not found: mautic | run the mautic-install skill |
credentials are incomplete | the message lists every missing value — set MAUTIC_BASE_URL, MAUTIC_API_USER, MAUTIC_API_KEY, or run mautic configure |
HTTP 401 | wrong credentials; for OAuth2 the token expired — mautic auth login |
HTTP 403 | the Mautic user's role lacks the permission — check mautic users self |
HTTP 404 on every command | the API is disabled (Configuration → API Settings), or the URL is not the instance root |
the response was not JSON | the URL points at the website rather than Mautic, or a login page came back |
HTTP 422 with rejected fields | wrong field alias or type — mautic fields list |
HTTP 429 | already retried with backoff; space the calls out or use --all instead of a loop |
... is destructive and was not performed | intended: re-run with --dry-run to inspect, --yes to proceed |
| write succeeded but nothing changed | the property name was not one Mautic knows — verify with get, check mautic fields list |
| wrong instance was touched | mautic auth status names the instance; select another with --profile <name> |
