jMautic

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.

Example

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.

Features

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).

How to Use

Dependencies

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:

• SLF4J API Module - 1.7.21
• ScribeJava Core - 3.2.0
• Jackson Databind - 2.8.4
• Joda Time - 2.9.4

If this project gets traction, I'll work on an easier way to integrate jMautic into your projects.

Writing Code

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.

Documentation

Here is the latest jMautic Javadoc.

How to Build

Just run

./gradlew jar

The code should be built on the build/libs/jMautic-[version].jar file.

How to Test

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

Contributing

Please do your Pull Requests. Any help is welcome :)

Licence

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.