jMautic is a Java client for the Mautic REST API. With it, you can write Java code to interact with several Mautic APIs, such as reading your contacts programatically.
src/test/java/com/leonardofischer/jmautic/examples/OAuth2Example.java
package com.leonardofischer.jmautic.examples;
import com.leonardofischer.jmautic.*;
import com.leonardofischer.jmautic.model.*;
import java.util.Iterator;
import java.util.Map;
import java.util.Scanner;
public class OAuth2Example {
public static void main(String [] args) {
try {
// Initialize a service
OAuth2Service service = new OAuth2Service()
.instanceUrl("YOUR MAUTIC INSTANCE URL")
.apiKey("API KEY")
.apiSecret("API SECRET")
.callbackUrl("AUTHORIZED CALLBACK URL")
.initService();
// Get authorization to access the Mautic API
String url = service.getAuthorizationUrl();
System.out.println("Go to '"+url+"', authorize, and paste the code here");
Scanner in = new Scanner(System.in);
String code = in.nextLine();
service.setAuthorizationCode(code);
MauticApi mauticApi = service.build();
// Execute API calls
ListContactsResult result = mauticApi.listContacts();
System.out.println("There are "+result.getTotal()+" contacts. These are "
+result.getContacts().size()+" of them:");
Iterator<Contact> contactsIterator = result.getContacts().iterator();
while( contactsIterator.hasNext() ) {
Contact contact = contactsIterator.next();
printContact(contact);
}
}
catch(MauticException e) {
e.printStackTrace();
}
}
static void printContact(Contact contact) {
System.out.print("- id="+contact.id+"; ");
Iterator it = contact.allFields.entrySet().iterator();
while( it.hasNext() ) {
Map.Entry field = (Map.Entry)it.next();
if( field.getValue()!=null ) {
System.out.print(field.getKey() + "="+field.getValue()+"; ");
}
}
System.out.println();
}
}
There are other examples in the com.leonardofischer.jmautic.examples package.
Right now, jMautic is able to:
- Access the Mautic REST API using Java (or any other JVM compatible language);
- Read contacts;
The implemented Mautic endpoints are accessible through the MauticApi class.
In the future, it should support:
- Access the Mautic REST API using OAuth1a;
- Updating contacts;
- Accessing other endpoints (such as Assets, Campaigns, Forms, Segments, Pages, etc).
Right now, you need to download or clone jMautic locally to build it. Then you need to include the build/libs/jMautic-0.0.1.jar file into your project. You also need to include the following .jars in your project:
If this project gets traction, I'll work on an easier way to integrate jMautic into your projects.
Create a instance of OAuth2Service
(right now jMautic supports OAuth2, but in the
future you may use other services here). Then configure the service with your Mautic instance access
tokens.
If its the first time connecting to the Mautic server, you need to authorize it. Use the
service.getAuthorizationUrl()
method to get a URL and send your user to that URL. The
user will need to enter their credentials and confirm that your application is able to connect with
his credentials. If the user confirms, Mautic will redirect the user to a callbackUrl
,
with a code
parameter. You need to set this code
in the
service.setAuthorizationCode(code)
method.
If the authorization process completes successfully, you can use
service.getAccessToken()
and service.getRefreshToken()
to reuse later when
creating the OAuth2Service
.
Finally, call service.build()
to get a MauticApi
instance. This object
has all the implemented methods from the Mautic API.
Read more about the authentication process in the OAuth2Service class Javadoc.
Here is the latest jMautic Javadoc.
Just run
./gradlew jar
The code should be built on the build/libs/jMautic-[version].jar
file.
Some jMautic tests need to connect to a real Mautic API to pass. You will need to configure the Mautic instance (as well as the API key and secret).
First, open jMauticTest.properties
and add valid configurations for
instanceUrl
, callbackUrl
, apiKey
and apiSecret
.
Some of the tests try to connect to a real Mautic Rest API, and will use the one on available on
these options.
Then, run
./gradlew configure
and follow the instructions on the output. This need to be done only once after you checkout the code.
Finally, run
./gradlew test
Please do your Pull Requests. Any help is welcome :)
jMautic is available under the MIT Licence.
Basically, you can use jMautic as you wish (you can use in commercial software too). Just point to https://github.com/lgfischer/jMautic when referring to jMautic. And jMautic has no guarantee, and its authors are not responsible for any consequences of using it.