Mautic API Essential Guide

What type of API does Mautic provide?

Type of API

Mautic has a REST API. It does not use GraphQL, SOAP, or other API types.

Key Features of Mautic's REST API

• It requires OAuth (1a or 2) authentication
• It supports GET, POST, DELETE, PATCH, and PUT requests
• Responses are returned in JSON format
• It allows programmatic creation, reading, deletion, and modification of different components within Mautic

Use Cases

The Mautic API can be used for:

• Building integrations with other systems like CRMs, ERPs, social media platforms, etc.
• Batch updating Mautic components
• Creating advanced triggers and alerts
• Achieving custom use cases envisioned by developers

Implementation

• Mautic provides a PHP REST API library for easier integration with PHP projects
• The API needs to be enabled in Mautic's configuration settings
• Developers need to create API credentials (Client ID and Client Secret) to use the API

Best Practices

• Use OAuth 2 for authorization when possible
• Don't hard-code authorization details; instead, create a secure form to input credentials
• Test API requests using the built-in API Tester provided in the Mautic API Library

Does the Mautic API have webhooks?

Yes, the official Mautic API does have webhooks. Here are the key points about Mautic webhooks:

Webhook Availability

Mautic provides webhooks as a universal way to send data about contacts, pages, forms, and events in real-time when actions occur.

Event Types

You can subscribe to various types of events in Mautic webhooks. Some of the available webhook events include:

• Form submit
• Contact created/updated
• Email opened
• Page hit
• Point changed
• Lead score changed

Webhook Workflow

1. Mautic checks if there is a webhook configured for a specific event (e.g., form submission).
2. If a webhook is found, Mautic sends the data to the URL defined in the webhook.
3. The receiving system processes the webhook payload.

Webhook Configuration

• You can configure webhooks to send events immediately or queue them for batch processing.
• Mautic allows you to set the order of events when they are queued (chronological or reverse chronological).

Webhook Security

• Mautic provides authenticity verification for webhooks using a secret key.
• A Webhook-Signature header is added to every webhook call, which can be verified by the receiving application.

Testing Webhooks

• Mautic offers a "Send Test Payload" button to test webhooks.
• You can use services like RequestBin to easily test and inspect webhook payloads.

Webhook Payload Structure

The webhook payload is structured as JSON, with the event type as the key and an array of event payloads as the value.

{
    "WebhookEventType": [
        { WebhookEventPayload }
    ]
}

In summary, Mautic's official API includes robust webhook functionality, allowing you to subscribe to various event types and receive real-time updates about contact activities and system events.

Rate Limits and other limitations

Based on the search results provided, there is no specific information about API rate limits for the Mautic API. However, here are the key points to consider regarding Mautic API usage and potential rate limits:

No Built-in Rate Limits

1. Mautic itself does not appear to have built-in API rate limits.

2. A Mautic developer mentioned that "API rate limit is not set in Mautic, but in your server settings".

Server-Dependent Limits

1. The rate at which you can make API calls is likely dependent on your server configuration and capabilities.

2. Better servers can handle higher traffic and potentially allow for more API calls.

Considerations for High Volume

1. When sending high volumes of data, you may need to experiment to determine the practical limits of your setup.

2. One user reported being able to send around 290 emails per minute using Mautic's spool and cronjob system.

3. Another user mentioned trying not to send faster than 200-300 emails per minute (up to 10k per hour) to maintain good deliverability.

Best Practices

1. It's recommended to test and gradually increase your API usage to find the optimal rate for your specific setup.

2. Consider implementing your own rate limiting or throttling mechanism in your application to prevent overwhelming your server or email delivery system.

3. Be mindful of email deliverability when sending high volumes - sending too fast can negatively impact your sender reputation.

While there are no specific API rate limits mentioned for Mautic, it's important to monitor your server performance and adjust your API usage accordingly. If you're experiencing issues with high-volume API calls, you may need to optimize your server configuration or implement your own rate limiting solution.

Latest API Version

Based on the search results, here are the key points regarding the most recent version of the Mautic API:

1. The most recent stable version of Mautic is 5.1.0, released on June 13, 2023 [2].

2. The latest version of the Mautic API library is 3.0.0, which was released on October 19, 2022. This version is fully compatible with Mautic 3 and later versions.

3. The Mautic API uses OAuth or Basic Authentication for authorization. As of Mautic 2.3.0, Basic Authentication is also supported.

4. The API supports both OAuth 1a and OAuth 2, but the administrator must choose one or the other.

5. For PHP projects, it is recommended to use the official Mautic PHP library available on GitHub.

6. The API version number is included in all API response headers since Mautic 2.4.0. The header name is 'Mautic-Version'.

7. Developers can check the Mautic version they are communicating with using the getMauticVersion() method in the PHP API library.

To summarize, while Mautic itself is at version 5.1.0, the most recent version of the Mautic API library is 3.0.0. This API library version is compatible with Mautic 3 and later versions, including the latest Mautic 5.x releases.

How to get a Mautic developer account and API Keys?

To get a developer account for Mautic and create an API integration, you need to follow these steps:

1. Enable the API in Mautic

1. Log in to your Mautic instance as an administrator.
2. Go to the Configuration page (located in the Settings menu).
3. Under API Settings, enable Mautic's API.
4. If you intend to use Basic Authentication, ensure you enable it. You can also choose which OAuth protocol to use here (OAuth 2 is recommended for Mautic 4+).
5. Save the configuration changes.

2. Create API Credentials

1. After enabling the API, go to the API Credentials page (located in the Settings menu).
2. Click on "New" to create a new set of API credentials.
3. Fill in the following details:
   • Name: Give your API integration a name
   • Callback/Redirect URI: Enter the URL where your application will be listening for responses from Mautic.
4. Click "Apply" to save the new credentials.

3. Obtain API Keys

1. Once you've created the API credentials, Mautic will generate a Client ID and Client Secret.
2. Copy these credentials as you'll need them to authenticate your API requests.

4. Implement Authentication in Your Application

1. Decide on the authentication method you'll use (OAuth 2 is recommended for newer Mautic versions).
2. Implement the chosen authentication method in your application using the Client ID and Client Secret you obtained.

5. Make API Requests

1. Use the base URL format for API requests: https://your-mautic.com/api/[request-extension].
2. Authenticate your requests using the method you implemented.
3. Make GET, POST, DELETE, PATCH, or PUT requests as needed to interact with Mautic data.

What can you do with the Mautic API?

Based on the search results, here are the key data models you can interact with using the Mautic API, along with what is possible for each:

Contacts

• Create, read, update, and delete contacts
• Get contact details and fields
• Add/remove contacts to/from segments
• Get contact's campaign memberships
• Get contact's stage changes
• Get contact's message queue data

Companies

• Create, read, update, and delete companies
• Associate/disassociate contacts with companies

Segments

• Create, read, update, and delete segments
• Add/remove contacts to/from segments

Campaigns

• Create, read, update, and delete campaigns
• Add/remove contacts to/from campaigns
• Get campaign contacts
• Get campaign events

Forms

• Create, read, update, and delete forms
• Get form submissions

Assets

• Create, read, update, and delete assets

Pages

• Create, read, update, and delete pages
• Get page hits

Emails

• Create, read, update, and delete emails
• Send emails
• Get email stats

Points

• Create, read, update, and delete point actions
• Add/subtract points from contacts

Stages

• Create, read, update, and delete stages
• Change a contact's stage

Notifications

• Create, read, update, and delete notifications

Reports

• Create, read, update, and delete reports
• Get report data

Users

• Create, read, update, and delete users

Roles

• Create, read, update, and delete roles

Categories

• Create, read, update, and delete categories

Dashboard

• Get dashboard widget data

The API allows for comprehensive interaction with most of Mautic's core entities and functionality. It provides the ability to manage contacts, campaigns, forms, emails and other key components programmatically.