Clés API

Créez, listez, renommez et révoquez les clés API d’un espace de travail.

URL de basehttps://api.emailit.com/v2Authentification Erreurs Limites de débit

POST/api-keys
GET/api-keys/{id}
GET/api-keys
POST/api-keys/{id}
POST/api-keys/{id}/regenerate
DEL/api-keys/{id}

Créer une clé API

Crée une clé API et renvoie son secret.

POST/api-keys

Nécessite une clé API full. Le secret contenu dans key n’est renvoyé que dans cette réponse et lorsque vous régénérez la clé : stockez-le immédiatement en lieu sûr. La clé sert aussi de mot de passe SMTP. Pour savoir ce que permet chaque portée, consultez Authentification.

Paramètres du corps

namestringobligatoire

Un nom qui indique où la clé est utilisée, comme Production web app. Doit être unique parmi les clés de l’espace de travail.

scopestringpar défaut : full

full pour accéder à tous les endpoints, ou sending pour les seuls endpoints d’envoi. Ne peut pas être modifiée par la suite.

sending_domain_idstring

L’ID d’un domaine d’envoi (dom_…) auquel restreindre une clé sending. La clé ne peut alors envoyer que depuis des adresses de ce domaine. Ignoré pour les clés full.

Réponse

Renvoie 201 avec l’objet clé API et son secret :

keystring

Le secret, qui commence par secret_. Utilisez-le comme jeton bearer. Il n’est plus jamais affiché.

POST/api-keys

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const apiKey = await emailit.apiKeys.create({
  name: 'Production web app',
  scope: 'sending',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

api_key = client.api_keys.create({
  "name": "Production web app",
  "scope": "sending",
})

PHP

$emailit = Emailit::client('your_api_key');

$apiKey = $emailit->apiKeys()->create([
  'name' => 'Production web app',
  'scope' => 'sending',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

api_key = client.api_keys.create(
  name: "Production web app",
  scope: "sending"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

apiKey, err := client.ApiKeys.Create(&emailit.CreateApiKeyRequest{
  Name:  "Production web app",
  Scope: "sending",
})

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let api_key = emailit.api_keys.create(
  emailit::types::CreateApiKeyParams::new("Production web app")
    .with_scope("sending")
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject apiKey = emailit.apiKeys().create(
  ApiKeyCreateParams.builder()
    .setName("Production web app")
    .setScope("sending")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var apiKey = emailit.ApiKeys.Create(new ApiKeyCreateOptions {
  Name = "Production web app",
  Scope = "sending",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$apiKey = Emailit::apiKeys()->create([
  'name' => 'Production web app',
  'scope' => 'sending',
]);

Terminal

curl -X POST https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production web app",
    "scope": "sending"
  }'

Terminal

curl -X POST https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production web app",
    "scope": "sending",
    "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey"
  }'

JavaScript

const apiKey = await emailit.apiKeys.create({
  name: 'Production web app',
  scope: 'sending',
  sending_domain_id: 'dom_4K468YrjOkR1wwdhqiO0G9XEUey',
});

Python

api_key = client.api_keys.create({
  "name": "Production web app",
  "scope": "sending",
  "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey",
})

JSON

{
  "object": "api_key",
  "id": "key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
  "name": "Production web app",
  "scope": "sending",
  "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey",
  "last_used_at": null,
  "created_at": "2026-10-01T09:40:18.204917Z",
  "updated_at": "2026-10-01T09:40:18.204917Z",
  "key": "secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG"
}

JSON

{
  "error": "Invalid sending_domain_id. Domain not found in workspace"
}

JSON

{
  "error": "API key with this name already exists",
  "existing": {
    "object": "api_key",
    "id": "key_4Kw6E8FodRivXbJlwPdn79gOxi1",
    "name": "Production web app"
  }
}

Récupérer une clé API

Récupère les détails d’une clé API. Le secret n’est pas inclus.

GET/api-keys/{id}

Nécessite une clé API full. Les clés supprimées sont introuvables.

Paramètres de chemin

idstringobligatoire

L’ID de la clé API (key_…) ou son nom. Encodez pour l’URL les noms qui contiennent des espaces.

Réponse

Renvoie l’objet clé API.

objectstring

Toujours api_key.

idstring

L’ID de la clé API.

namestring

Le nom de la clé.

scopestring

full ou sending.

sending_domain_idstring | null

L’ID du domaine d’envoi auquel la clé est restreinte, ou null.

last_used_atstring | null

Date à laquelle la clé a authentifié une requête pour la dernière fois, ou null si elle n’a pas été utilisée depuis sa création ou sa régénération.

created_atstring

Date de création de la clé.

updated_atstring

Date à laquelle la clé a été renommée ou régénérée pour la dernière fois.

GET/api-keys/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const apiKey = await emailit.apiKeys.get('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

api_key = client.api_keys.get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB")

PHP

$emailit = Emailit::client('your_api_key');

$apiKey = $emailit->apiKeys()->get('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

api_key = client.api_keys.get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

apiKey, err := client.ApiKeys.Get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let api_key = emailit.api_keys.get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB").await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject apiKey = emailit.apiKeys().get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var apiKey = emailit.ApiKeys.Get("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB");

PHP

use Emailit\Laravel\Facades\Emailit;

$apiKey = Emailit::apiKeys()->get('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB');

Terminal

curl https://api.emailit.com/v2/api-keys/key_4KEaYMnfrxQGkuB0svwiuyt0ZhB \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "api_key",
  "id": "key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
  "name": "Production web app",
  "scope": "sending",
  "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey",
  "last_used_at": "2026-10-01T11:58:02.000000Z",
  "created_at": "2026-10-01T09:40:18.204917Z",
  "updated_at": "2026-10-01T09:40:18.204917Z"
}

JSON

{
  "error": "API key not found"
}

Lister les clés API

Renvoie une page des clés API de l’espace de travail, de la plus récente à la plus ancienne.

GET/api-keys

Nécessite une clé API full. Les clés supprimées et les secrets ne sont pas inclus. Consultez last_used_at pour repérer les clés que vous n’utilisez plus.

Paramètres de requête

pageintegerpar défaut : 1

La page à renvoyer.

limitintegerpar défaut : 10

Nombre de clés par page, de 1 à 100.

searchstring

Recherche insensible à la casse sur le nom de la clé.

matchstringpar défaut : all

all ou or. Mode de combinaison des filtres ci-dessous.

orderstring

Une clé de filtre à utiliser pour le tri.

directionstring

asc ou desc.

Filtres

Ajoutez des filtres sous la forme key.condition=value, par exemple scope.exact=sending. Consultez Filtrage et tri.

Clé	Type	Remarques
`name`	string
`scope`	string	`full` ou `sending`.
`type`	string	Type d’identifiant. Les clés créées dans le tableau de bord ou via l’API sont de type `api`.
`created_at`	date

Chaque clé est aussi une clé de tri.

Réponse

Renvoie un tableau data d’objets clé API avec next_page_url et previous_page_url. Consultez Pagination.

GET/api-keys

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const apiKeys = await emailit.apiKeys.list();

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

api_keys = client.api_keys.list()

PHP

$emailit = Emailit::client('your_api_key');

$apiKeys = $emailit->apiKeys()->list();

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

api_keys = client.api_keys.list

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

apiKeys, err := client.ApiKeys.List(nil)

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let api_keys = emailit.api_keys.list(None).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject apiKeys = emailit.apiKeys().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var apiKeys = emailit.ApiKeys.List();

PHP

use Emailit\Laravel\Facades\Emailit;

$apiKeys = Emailit::apiKeys()->list();

Terminal

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "data": [
    {
      "object": "api_key",
      "id": "key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
      "name": "Production web app",
      "scope": "sending",
      "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey",
      "last_used_at": "2026-10-01T11:58:02.000000Z",
      "created_at": "2026-10-01T09:40:18.204917Z",
      "updated_at": "2026-10-01T09:40:18.204917Z"
    },
    {
      "object": "api_key",
      "id": "key_4Kw6E8FodRivXbJlwPdn79gOxi1",
      "name": "Back office",
      "scope": "full",
      "sending_domain_id": null,
      "last_used_at": null,
      "created_at": "2026-09-02T14:21:07.613508Z",
      "updated_at": "2026-09-02T14:21:07.613508Z"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Mettre à jour une clé API

Renomme une clé API.

POST/api-keys/{id}

Nécessite une clé API full. Seul le nom peut être modifié. Pour changer la portée ou la restriction de domaine, créez une nouvelle clé et supprimez celle-ci. Pour remplacer le secret, régénérez la clé.

Paramètres de chemin

idstringobligatoire

L’ID de la clé API ou son nom actuel.

Paramètres du corps

namestringobligatoire

Le nouveau nom. Doit être unique parmi les clés de l’espace de travail.

Réponse

Renvoie l’objet clé API mis à jour.

POST/api-keys/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const apiKey = await emailit.apiKeys.update('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB', {
  name: 'Production web app (EU)',
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

api_key = client.api_keys.update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB", {
  "name": "Production web app (EU)",
})

PHP

$emailit = Emailit::client('your_api_key');

$apiKey = $emailit->apiKeys()->update('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB', [
  'name' => 'Production web app (EU)',
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

api_key = client.api_keys.update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB", name: "Production web app (EU)")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

apiKey, err := client.ApiKeys.Update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB", &emailit.UpdateApiKeyRequest{
  Name: "Production web app (EU)",
})

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

let api_key = emailit.api_keys.update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
  emailit::types::UpdateApiKeyParams {
    name: Some("Production web app (EU)".into()),
    ..Default::default()
  }
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject apiKey = emailit.apiKeys().update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
  ApiKeyUpdateParams.builder()
    .setName("Production web app (EU)")
    .build()
);

using Emailit;

var emailit = new EmailitClient("your_api_key");

var apiKey = emailit.ApiKeys.Update("key_4KEaYMnfrxQGkuB0svwiuyt0ZhB", new ApiKeyUpdateOptions {
  Name = "Production web app (EU)",
});

PHP

use Emailit\Laravel\Facades\Emailit;

$apiKey = Emailit::apiKeys()->update('key_4KEaYMnfrxQGkuB0svwiuyt0ZhB', [
  'name' => 'Production web app (EU)',
]);

Terminal

curl -X POST https://api.emailit.com/v2/api-keys/key_4KEaYMnfrxQGkuB0svwiuyt0ZhB \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production web app (EU)"
  }'

JSON

{
  "object": "api_key",
  "id": "key_4KEaYMnfrxQGkuB0svwiuyt0ZhB",
  "name": "Production web app (EU)",
  "scope": "sending",
  "sending_domain_id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey",
  "last_used_at": "2026-10-01T11:58:02.000000Z",
  "created_at": "2026-10-01T09:40:18.204917Z",
  "updated_at": "2026-10-01T12:10:33.000000Z"
}

JSON

{
  "error": "API key not found"
}

JSON

{
  "error": "Another API key with this name already exists"
}

Régénérer une clé API

Remplace le secret de la clé par un nouveau. L’ancien secret cesse immédiatement de fonctionner pour les requêtes API et les nouvelles connexions SMTP. La clé conserve son ID, son nom, sa portée et son domaine d’envoi, et last_used_at est réinitialisé. Nécessite une clé API de portée full.

Le nouveau secret n’est renvoyé que dans cette réponse. Enregistrez-le immédiatement, puis mettez à jour chaque application et chaque client SMTP qui utilisait l’ancien. Si vous régénérez la clé qui effectue cette requête, utilisez le nouveau secret pour les requêtes suivantes.

POST/api-keys/{id}/regenerate

Paramètres de chemin

idstringobligatoire

L’ID de la clé API (key_…) ou le nom de la clé.

Réponse

Renvoie l’objet clé API avec le nouveau secret dans key.

keystring

Le nouveau secret : secret_ suivi de 32 lettres et chiffres. Affiché une seule fois.

scopestring

full ou sending.

sending_domain_idstring | null

Le domaine d’envoi auquel une clé sending est limitée, ou null.

last_used_atnull

Toujours null après une régénération.

Renvoie 404 si aucune clé API active ne correspond à id.

POST/api-keys/{id}/regenerate

Terminal

curl -X POST https://api.emailit.com/v2/api-keys/key_3t4p05pmtgBssZzXRT0QmJn3UgH/regenerate \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JavaScript

const res = await fetch('https://api.emailit.com/v2/api-keys/key_3t4p05pmtgBssZzXRT0QmJn3UgH/regenerate', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { key } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/api-keys/key_3t4p05pmtgBssZzXRT0QmJn3UgH/regenerate",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
new_secret = r.json()["key"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('api-keys/key_3t4p05pmtgBssZzXRT0QmJn3UgH/regenerate', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$newSecret = json_decode($response->getBody(), true)['key'];

JSON

{
  "object": "api_key",
  "id": "key_3t4p05pmtgBssZzXRT0QmJn3UgH",
  "name": "Production server",
  "key": "secret_tbgPKVFk7QMi1nneTKdFcUWTyh8XoPz3",
  "scope": "sending",
  "sending_domain_id": "dom_3bTLTaNUAcCiXuokxifeIYdFOYf",
  "last_used_at": null,
  "created_at": "2026-09-12 08:01:44.120931+00",
  "updated_at": "2026-10-01T13:15:07.402881Z"
}

JSON

{
  "error": "API key not found"
}

Supprimer une clé API

Révoque une clé API. Les requêtes et les connexions SMTP qui utilisent son secret échouent dès lors.

DELETE/api-keys/{id}

Nécessite une clé API full. Vous pouvez supprimer la clé avec laquelle vous effectuez l’appel : assurez-vous d’abord que votre intégration dispose d’une autre clé. Une clé supprimée n’apparaît plus dans Lister les clés API, et son nom redevient disponible pour une nouvelle clé. Les e-mails déjà envoyés avec la clé ne sont pas affectés.

Paramètres de chemin

idstringobligatoire

L’ID de la clé API ou son nom.

Réponse

objectstring

Toujours api_key.

idstring

L’ID de la clé supprimée.

namestring

Le nom de la clé.

deletedboolean

Toujours true.

DELETE/api-keys/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.apiKeys.delete('key_4Kw6E8FodRivXbJlwPdn79gOxi1');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.api_keys.delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1")

PHP

$emailit = Emailit::client('your_api_key');

$emailit->apiKeys()->delete('key_4Kw6E8FodRivXbJlwPdn79gOxi1');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.api_keys.delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.ApiKeys.Delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1")

Rust

use emailit::Emailit;

let emailit = Emailit::new("your_api_key");

emailit.api_keys.delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1").await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

emailit.apiKeys().delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1");

using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.ApiKeys.Delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::apiKeys()->delete('key_4Kw6E8FodRivXbJlwPdn79gOxi1');

Terminal

curl -X DELETE https://api.emailit.com/v2/api-keys/key_4Kw6E8FodRivXbJlwPdn79gOxi1 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

JSON

{
  "object": "api_key",
  "id": "key_4Kw6E8FodRivXbJlwPdn79gOxi1",
  "name": "Back office",
  "deleted": true
}

JSON

{
  "error": "API key not found"
}