This page documents every Mautic REST API endpoint the plugin calls. All requests are made through the MauticApiClient class, which wraps wp_remote_request() and handles authentication headers (Basic Auth or OAuth2 Bearer token), JSON encoding, error handling, and automatic token refresh for OAuth2.
All endpoint paths are relative to your Mautic instance URL. For example, if your Mautic URL is https://mautic.example.com, the full URL for /api/contacts/new would be https://mautic.example.com/api/contacts/new.
Contacts
Create Contact
Property
Value
Method
POST
Endpoint
/api/contacts/new
When Called
When creating a new contact that does not yet exist in Mautic. Called by the createOrUpdateContact() method when no existing contact is found by email.
Data Sent
JSON object containing contact fields: email, firstname, lastname, phone, address1, city, state, zipcode, country, tags (array), and any custom fields such as mautic_woo_order_data, mautic_woo_cart_data, mautic_woo_recovery_url, mautic_woo_total_spent, mautic_woo_order_count, mautic_woo_coupon_code.
Edit Contact
Property
Value
Method
PATCH
Endpoint
/api/contacts/{id}/edit
When Called
When updating an existing contact in Mautic. Called by the createOrUpdateContact() method when an existing contact is found by email. Also called directly to update the coupon code field after abandoned cart sync and to clear cart data fields on recovery.
Data Sent
JSON object with the fields to update. Only changed fields need to be included. The {id} path parameter is the Mautic contact ID.
Get Contact
Property
Value
Method
GET
Endpoint
/api/contacts/{id}
When Called
When retrieving a specific contact by their Mautic ID.
Data Sent
None. The {id} path parameter is the Mautic contact ID.
Search Contacts by Email
Property
Value
Method
GET
Endpoint
/api/contacts
When Called
When looking up a contact by email address before creating or updating. Also used by the connection test to verify connectivity.
Data Sent
Query parameters: search=email:user@example.com and limit=1 for email lookups, or limit=1 alone for connection tests.
Contact Fields
Get Contact Fields
Property
Value
Method
GET
Endpoint
/api/fields/contact
When Called
When checking which custom fields exist in Mautic. Called by the “Check Fields” button on the Mautic Fields settings tab and by the auto-create fields logic.
Data Sent
None.
Create Contact Field
Property
Value
Method
POST
Endpoint
/api/fields/contact/new
When Called
When creating a missing custom field in Mautic. Called by the “Create Fields” button on the Mautic Fields tab and by the auto-create logic during abandoned cart sync and order sync.
Data Sent
JSON object: label (display name), alias (machine name), type (field type: text, url, or number).
The plugin uses the following custom field aliases:
Alias
Label
Type
Purpose
mautic_woo_order_data
Last Order Data
text
JSON string containing the latest order details (order ID, status, total, discount, coupons, currency, date, payment method, and line items).
The full URL a customer can click to restore their abandoned cart and go to checkout.
mautic_woo_total_spent
Total Spent
number
The customer’s lifetime total spent in WooCommerce.
mautic_woo_order_count
Order Count
number
The total number of orders the customer has placed in WooCommerce.
mautic_woo_coupon_code
Recovery Coupon Code
text
The WooCommerce coupon code generated for abandoned cart recovery emails.
Tags
Get Tags
Property
Value
Method
GET
Endpoint
/api/tags
When Called
When retrieving existing tags from Mautic.
Data Sent
None.
Create Tag
Property
Value
Method
POST
Endpoint
/api/tags/new
When Called
When creating a new tag in Mautic that does not already exist.
Data Sent
JSON object: tag (the tag name string).
Notes
Create Note
Property
Value
Method
POST
Endpoint
/api/notes/new
When Called
When the “Add Notes” option is enabled in Order Sync settings. A note is created on the Mautic contact after each order sync.
Data Sent
JSON object: lead (Mautic contact ID), type ("general"), text (note title and body separated by a newline, containing order and product details).
Emails
Send Email to Contact
Property
Value
Method
POST
Endpoint
/api/emails/{email_id}/contact/{contact_id}/send
When Called
When the Email Trigger feature is enabled in Order Sync settings and a template ID is configured for the current order status. Sends a transactional email via Mautic when an order transitions to a specific status.
Data Sent
JSON object: tokens (optional key-value pairs for template variable replacement). The {email_id} and {contact_id} path parameters are the Mautic email template ID and contact ID respectively.
When the Abandoned Cart module has a segment ID configured. After syncing an abandoned cart to Mautic, the contact is added to the specified segment.
Data Sent
None. The {segment_id} and {contact_id} path parameters are the Mautic segment ID and contact ID respectively.
Authentication
All API requests include authentication headers managed by the AuthFactory class. The plugin supports two authentication methods:
Basic Auth – Sends an Authorization: Basic header with Base64-encoded username and password credentials.
OAuth2 – Sends an Authorization: Bearer header with the access token. If a 401 response is received, the plugin automatically attempts to refresh the token and retry the request once.
Request Headers
Every API request includes the following headers in addition to the authentication header:
Header
Value
Content-Type
application/json
Accept
application/json
Error Handling
The API client handles errors at multiple levels:
WordPress HTTP errors – If wp_remote_request() returns a WP_Error, the error message is captured and returned in the response array.
HTTP 4xx/5xx responses – If the Mautic server returns a status code of 400 or higher, the error message is extracted from the response body.
OAuth2 token expiration – If a 401 response is received with OAuth2 authentication, the plugin automatically refreshes the access token and retries the request once.
Unique email conflicts – If creating a contact fails because the email already exists, the plugin retries the operation as an edit.
Region field rejections – If Mautic rejects the state or country fields, the plugin retries without those fields.
