API Xitroo

Utilisez Xitroo depuis votre propre code : recevez les e-mails de confirmation dans vos tests de bout en bout, automatisez les inscriptions ou envoyez des e-mails depuis n’importe quelle adresse @xitroo.fr.

Comment obtenir votre clé API

1

Choisissez une offre

Choisissez Developer, Team ou Business ci-dessous et cliquez sur S'abonner.

2

Payez en toute sécurité avec Stripe

Carte ou autres moyens de paiement. Mensuel en dollars US, facture par e-mail, résiliable à tout moment.

3

Recevez votre clé

Votre clé (xit_…) s'affiche juste après le paiement et vous est aussi envoyée par e-mail.

Clé perdue ? En demander une nouvelle →

Offres

plus TVA applicable, facturé mensuellement en dollars US, résiliable à tout moment

Gérer votre abonnement

Changer d'offre, modifier le paiement, télécharger les factures ou résilier. Saisissez votre clé API.

Clé API perdue ?

Saisissez l'adresse e-mail de votre abonnement. Nous vous envoyons une nouvelle clé ; l'ancienne ne fonctionne plus.

Démarrage rapide

  1. Obtenez votre clé API (voir ci-dessus) : elle s’affiche juste après le paiement et vous est aussi envoyée par e-mail. Elle commence par xit_.
  2. Envoyez-la dans l’en-tête X-Api-Key à chaque requête.
  3. Toute adresse @xitroo.fr, @xitroo.com ou @xitroo.de fonctionne immédiatement. Les e-mails sont supprimés après 48 heures.
curl -H "X-Api-Key: $XITROO_API_KEY" \
  "https://api.xitroo.com/v1/mails?mailAddress=mon-test-42@xitroo.fr&mailsPerPage=25&minTimestamp=0&maxTimestamp=$(date +%s)&locale=en"

URL de base : https://api.xitroo.com/v1 · toutes les réponses sont en JSON · la clé ne va jamais dans l’URL.

Exemples

Code testé dans huit langages. Définissez la variable d’environnement XITROO_API_KEY avec votre clé.

Attendre un e-mail de confirmation

ADDRESS="my-test-42@xitroo.com"
SINCE=$(date +%s)
# ... sign up with $ADDRESS in your app ...
while :; do
  sleep 2
  ID=$(curl -s -H "X-Api-Key: $XITROO_API_KEY" \
    "https://api.xitroo.com/v1/mails?mailAddress=$ADDRESS&mailsPerPage=10&minTimestamp=$SINCE&maxTimestamp=$(( $(date +%s) + 60 ))&locale=en" \
    | jq -r '.mails[0]._id // empty')
  [ -n "$ID" ] && break
done
curl -s -H "X-Api-Key: $XITROO_API_KEY" \
  "https://api.xitroo.com/v1/mail?id=$ID&locale=en" | jq -r .subject
<?php
$api = 'https://api.xitroo.com/v1';
$ctx = stream_context_create(['http' => [
    'header' => 'X-Api-Key: ' . getenv('XITROO_API_KEY'),
    'ignore_errors' => true,
]]);
$address = 'my-test-42@xitroo.com';
$since = time();
// ... sign up with $address in your app ...
do {
    sleep(2);
    $query = http_build_query([
        'mailAddress' => $address, 'mailsPerPage' => 10, 'locale' => 'en',
        'minTimestamp' => $since, 'maxTimestamp' => time() + 60,
    ]);
    $list = json_decode(file_get_contents("$api/mails?$query", false, $ctx), true);
} while (empty($list['mails']));

$id = $list['mails'][0]['_id'];
$mail = json_decode(file_get_contents("$api/mail?id=$id&locale=en", false, $ctx), true);
echo $mail['subject'], PHP_EOL;
// Node.js 18+, save as wait.mjs
const API = "https://api.xitroo.com/v1";
const headers = { "X-Api-Key": process.env.XITROO_API_KEY };
const address = "my-test-42@xitroo.com";
const since = Math.floor(Date.now() / 1000);
// ... sign up with address in your app ...
let list;
do {
  await new Promise((r) => setTimeout(r, 2000));
  const q = new URLSearchParams({
    mailAddress: address, mailsPerPage: 10, locale: "en",
    minTimestamp: since, maxTimestamp: Math.floor(Date.now() / 1000) + 60,
  });
  list = await (await fetch(`${API}/mails?${q}`, { headers })).json();
} while (!list.mails);

const id = list.mails[0]._id;
const mail = await (await fetch(`${API}/mail?id=${id}&locale=en`, { headers })).json();
console.log(mail.subject);
import os, time, requests

API = "https://api.xitroo.com/v1"
HEADERS = {"X-Api-Key": os.environ["XITROO_API_KEY"]}
address = "my-test-42@xitroo.com"
since = int(time.time())
# ... sign up with address in your app ...
while True:
    time.sleep(2)
    data = requests.get(f"{API}/mails", headers=HEADERS, params={
        "mailAddress": address, "mailsPerPage": 10, "locale": "en",
        "minTimestamp": since, "maxTimestamp": int(time.time()) + 60}).json()
    if data.get("mails"):
        break

mail_id = data["mails"][0]["_id"]
mail = requests.get(f"{API}/mail", headers=HEADERS,
                    params={"id": mail_id, "locale": "en"}).json()
print(mail["subject"])
require "net/http"
require "json"

API = "https://api.xitroo.com/v1"

def get(path, params)
  uri = URI("#{API}#{path}")
  uri.query = URI.encode_www_form(params)
  req = Net::HTTP::Get.new(uri)
  req["X-Api-Key"] = ENV.fetch("XITROO_API_KEY")
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
  JSON.parse(res.body)
end

address = "my-test-42@xitroo.com"
since = Time.now.to_i
# ... sign up with address in your app ...
list = {}
until list["mails"]
  sleep 2
  list = get("/mails", mailAddress: address, mailsPerPage: 10, locale: "en",
                       minTimestamp: since, maxTimestamp: Time.now.to_i + 60)
end

mail = get("/mail", id: list["mails"][0]["_id"], locale: "en")
puts mail["subject"]
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"time"
)

const api = "https://api.xitroo.com/v1"

func get(path string, params url.Values, out any) error {
	req, _ := http.NewRequest("GET", api+path+"?"+params.Encode(), nil)
	req.Header.Set("X-Api-Key", os.Getenv("XITROO_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	return json.NewDecoder(res.Body).Decode(out)
}

func main() {
	address := "my-test-42@xitroo.com"
	since := time.Now().Unix()
	// ... sign up with address in your app ...
	var list struct {
		Mails []struct {
			ID string `json:"_id"`
		} `json:"mails"`
	}
	for len(list.Mails) == 0 {
		time.Sleep(2 * time.Second)
		get("/mails", url.Values{
			"mailAddress": {address}, "mailsPerPage": {"10"}, "locale": {"en"},
			"minTimestamp": {strconv.FormatInt(since, 10)},
			"maxTimestamp": {strconv.FormatInt(time.Now().Unix()+60, 10)},
		}, &list)
	}

	var mail struct {
		Subject string `json:"subject"`
	}
	get("/mail", url.Values{"id": {list.Mails[0].ID}, "locale": {"en"}}, &mail)
	fmt.Println(mail.Subject)
}
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class WaitForMail {
    static final String API = "https://api.xitroo.com/v1";
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String get(String pathAndQuery) throws Exception {
        HttpRequest req = HttpRequest.newBuilder(URI.create(API + pathAndQuery))
            .header("X-Api-Key", System.getenv("XITROO_API_KEY")).build();
        return HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
    }

    public static void main(String[] args) throws Exception {
        String address = URLEncoder.encode("my-test-42@xitroo.com", StandardCharsets.UTF_8);
        long since = System.currentTimeMillis() / 1000;
        // ... sign up with the address in your app ...
        Matcher id;
        do {
            Thread.sleep(2000);
            long until = System.currentTimeMillis() / 1000 + 60;
            String list = get("/mails?mailAddress=" + address + "&mailsPerPage=10&locale=en"
                + "&minTimestamp=" + since + "&maxTimestamp=" + until);
            id = Pattern.compile("\"_id\":\"([0-9a-f]{24})\"").matcher(list);
        } while (!id.find());

        // JSON with subject, bodyText, bodyHtml, ... (parse it with your JSON library)
        System.out.println(get("/mail?id=" + id.group(1) + "&locale=en"));
    }
}
// .NET 6+ (dotnet new console), Program.cs
using System.Net.Http.Json;
using System.Text.Json;

var api = "https://api.xitroo.com/v1";
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("XITROO_API_KEY"));

var address = Uri.EscapeDataString("my-test-42@xitroo.com");
var since = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
// ... sign up with the address in your app ...
JsonElement mails;
while (true)
{
    await Task.Delay(2000);
    var until = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + 60;
    var list = await http.GetFromJsonAsync<JsonElement>(
        $"{api}/mails?mailAddress={address}&mailsPerPage=10&locale=en&minTimestamp={since}&maxTimestamp={until}");
    if (list.TryGetProperty("mails", out mails)) break;
}

var id = mails[0].GetProperty("_id").GetString();
var mail = await http.GetFromJsonAsync<JsonElement>($"{api}/mail?id={id}&locale=en");
Console.WriteLine(mail.GetProperty("subject").GetString());

Envoyer un e-mail

curl -X POST https://api.xitroo.com/v1/mail/send/premium \
  -H "X-Api-Key: $XITROO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "my-test-42@xitroo.com",
    "recipient": "you@example.com",
    "subject": "Hello",
    "bodyText": "Sent with the Xitroo API"
  }'
# reply: add "replyMailID": "<_id of a received mail>"
<?php
$ctx = stream_context_create(['http' => [
    'method' => 'POST',
    'header' => "Content-Type: application/json\r\n"
              . 'X-Api-Key: ' . getenv('XITROO_API_KEY'),
    'content' => json_encode([
        'from'      => 'my-test-42@xitroo.com',
        'recipient' => 'you@example.com',
        'subject'   => 'Hello',
        'bodyText'  => 'Sent with the Xitroo API',
        // 'replyMailID' => '<_id of a received mail>',
    ]),
    'ignore_errors' => true,
]]);
echo file_get_contents('https://api.xitroo.com/v1/mail/send/premium', false, $ctx), PHP_EOL;
// Node.js 18+, save as send.mjs
const res = await fetch("https://api.xitroo.com/v1/mail/send/premium", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.XITROO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "my-test-42@xitroo.com",
    recipient: "you@example.com",
    subject: "Hello",
    bodyText: "Sent with the Xitroo API",
    // replyMailID: "<_id of a received mail>",
  }),
});
console.log(res.status, await res.json());
import os, requests

r = requests.post(
    "https://api.xitroo.com/v1/mail/send/premium",
    headers={"X-Api-Key": os.environ["XITROO_API_KEY"]},
    json={
        "from": "my-test-42@xitroo.com",
        "recipient": "you@example.com",
        "subject": "Hello",
        "bodyText": "Sent with the Xitroo API",
        # "replyMailID": "<_id of a received mail>",
    },
)
print(r.status_code, r.json())
require "net/http"
require "json"

uri = URI("https://api.xitroo.com/v1/mail/send/premium")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json",
                               "X-Api-Key" => ENV.fetch("XITROO_API_KEY"))
req.body = {
  from: "my-test-42@xitroo.com",
  recipient: "you@example.com",
  subject: "Hello",
  bodyText: "Sent with the Xitroo API"
  # replyMailID: "<_id of a received mail>"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
puts res.code, res.body
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"from":      "my-test-42@xitroo.com",
		"recipient": "you@example.com",
		"subject":   "Hello",
		"bodyText":  "Sent with the Xitroo API",
		// "replyMailID": "<_id of a received mail>",
	})
	req, _ := http.NewRequest("POST", "https://api.xitroo.com/v1/mail/send/premium", bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", os.Getenv("XITROO_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SendMail {
    public static void main(String[] args) throws Exception {
        String json = """
            {"from": "my-test-42@xitroo.com", "recipient": "you@example.com",
             "subject": "Hello", "bodyText": "Sent with the Xitroo API"}""";
        HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.xitroo.com/v1/mail/send/premium"))
            .header("Content-Type", "application/json")
            .header("X-Api-Key", System.getenv("XITROO_API_KEY"))
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.statusCode() + " " + res.body());
    }
}
// .NET 6+ (dotnet new console), Program.cs
using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("XITROO_API_KEY"));

var res = await http.PostAsJsonAsync("https://api.xitroo.com/v1/mail/send/premium", new
{
    @from = "my-test-42@xitroo.com",
    recipient = "you@example.com",
    subject = "Hello",
    bodyText = "Sent with the Xitroo API",
    // replyMailID = "<_id of a received mail>",
});
Console.WriteLine($"{(int)res.StatusCode} {await res.Content.ReadAsStringAsync()}");

Recevoir des e-mails

Lister une boîte

GET /v1/mails

Paramètre Obligatoire Description
mailAddress oui Adresse complète, p. ex. mon-test-42@xitroo.fr
mailsPerPage oui 1 – 200
minTimestamp oui Secondes Unix ; seulement les e-mails arrivés après
maxTimestamp oui Secondes Unix ; seulement les e-mails arrivés avant (au plus une heure dans le futur)
locale oui en ou de (langue des messages d’erreur)

Réponse, les plus récents d’abord :

{
  "totalMails": 2,
  "mails": [
    { "_id": "6748f1c2a1b2c3d4e5f60718", "from": "noreply@example.com",
      "subject": "Confirmez votre compte", "arrivalTimestamp": 1793786065.12 }
  ]
}

Une boîte vide répond HTTP 200 avec {"type": "empty response", ...} au lieu d’une liste.

Attendre un e-mail : fixez minTimestamp à l’heure de début de votre test pour ne voir que les nouveaux e-mails.

Lire un e-mail

GET /v1/mail?id=<_id>&locale=en

Renvoie deliveredTo, from, subject, arrivalTimestamp, expireTimestamp, bodyText, bodyHtml, rawHeader, messageID et attachments (noms de fichiers).

Pièces jointes

GET /v1/mail/attachment?id=<_id>&filename=<nom>&locale=en renvoie le fichier.

Envoyer des e-mails

POST /v1/mail/send/premium avec l’en-tête X-Api-Key et un corps JSON :

Champ Obligatoire Description
from oui Votre adresse d’expéditeur, se terminant par @xitroo.fr, @xitroo.com ou @xitroo.de
recipient oui Exactement une adresse de destinataire
subject oui Jusqu’à 200 caractères, sans saut de ligne
bodyText oui Texte brut, jusqu’à 100 Ko
replyMailID non _id d’un e-mail reçu : votre e-mail est envoyé en réponse
curl -X POST https://api.xitroo.com/v1/mail/send/premium \
  -H "X-Api-Key: $XITROO_API_KEY" -H "Content-Type: application/json" \
  -d '{"from":"mon-test-42@xitroo.fr","recipient":"support@example.com","subject":"Bonjour","bodyText":"Bonjour !"}'
{ "sendSuccess": true, "sendsPerMonth": 1000, "sentThisMonth": 17 }

Les réponses envoyées à votre adresse Xitroo arrivent dans sa boîte comme tout autre e-mail. Le quota mensuel repart le 1er de chaque mois (UTC) ; au plus 10 e-mails par minute.

Limites et erreurs

HTTP code Signification
400 PARAMETER_INVALID, PARAMETER_REQUIRED Paramètre manquant ou invalide ; voir le champ parameter
401 INVALID_API_KEY Clé absente, erronée ou abonnement inactif
429 RATE_LIMITED Trop de requêtes ; attendez Retry-After secondes
429 QUOTA_EXCEEDED Quota mensuel d’envoi épuisé
502 SEND_FAILED Le serveur de mail n’a pas accepté l’e-mail ; non décompté du quota

Chaque erreur est en JSON : {"status": 429, "code": "RATE_LIMITED", "message": "...", "retryAfter": 12}.

Gardez votre clé secrète : utilisez-la uniquement depuis des serveurs ou la CI, jamais dans une page web ou une application publique.

Facturation

Les abonnements sont mensuels et facturés en dollars US par Stripe ; vous recevez une facture par e-mail chaque mois. Changez d’offre, de carte, téléchargez vos factures ou résiliez à tout moment dans le portail client (voir Gérer votre abonnement ci-dessus). Après résiliation, votre clé fonctionne jusqu’à la fin de la période payée.