GitLab provides [[http://doc.gitlab.com/ce/api/ | a powerful API]] that lets you interact programmatically with a GitLab instance in order to automate a lot of things.

This tutorial presents how to use the API of GitLab with [[https://www.python.org | Python]]. Of course you can use your favorite language.

> For the examples below we will use the instance https://gitlab.example.org. Of course you can use https://gitlab.com. 

====== Get the list of users registered in GitLab ======

This first example is fairly easy and takes advantage of the [[http://doc.gitlab.com/ce/api/users.html | Users resource]].

<code python>
#! /usr/bin/env python
#-*- coding: utf-8 -*-

import requests
import json

# your private token can be found here:
# https://gitlab.example.org/profile/account
TOKEN = "<your-private-token>"

r = requests.get("https://gitlab.example.org/api/v3/users?per_page=100&private_token="+TOKEN)

if r.status_code == 200:
    users = json.loads(r.content)
    for user in users:
        print user["username"], user["email"]
</code>

The //requests// library is used to query the API and the //json// library is used to parse the result received from the server. Here the result is simply a list of users.


====== Send an email to the members of a GitLab group ======

Again, this is pretty easy. We will need the [[http://doc.gitlab.com/ce/api/groups.html | Groups]] resource and the [[http://doc.gitlab.com/ce/api/users.html | Users]] resource.

In order to send the email, we will simply use the [[http://www.mutt.org/ | Mutt]] email client.

The Mutt command will look like this:

<code bash>
$ mutt -s "The subject" `./get_recipents.py <group-id> /dev/null` < message.txt
</code>

As you can see, Mutt needs three parameters:
  * the subject of the email. Will be given in parameter;
  * the message to be sent. Will be given through a Unix pipeline (//message.txt//);
  * the list of recipients (members of the GitLab group). Will be given in parameter as the result of a Python script.

As you can expect, the Python script will use the API of GitLab in order to get the list of recipients.
Below you will find a working script:

<code python>
#! /usr/bin/env python
#-*- coding: utf-8 -*-

import requests
import json

# your private token can be found here:
# https://gitlab.example.org/profile/account
TOKEN = "<your-private-token>"
GROUP_ID = 21

EMAILS = []

r = requests.get("https://gitlab.example.org/api/v3/groups/" + str(GROUP_ID) + "/members?private_token=" + TOKEN)

if r.status_code == 200:
    members = json.loads(r.content)
    for member in members:
        r = requests.get("https://gitlab.example.org/api/v3/users/" + str(member["id"]) + "?private_token=" + TOKEN)
        if r.status_code == 200:
            user = json.loads(r.content)
            if user["state"] == "active":
                EMAILS.append(user["email"])
</code>

A first request to the //Groups// resource returns the list of members in the group. The ''for'' loop iterates through these members in order to get their email.

Only active users (//user["state"] == "active"//) will receive the email.