Chiavi API

Crea, elenca, rinomina e revoca le chiavi API di un workspace.

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

Crea una chiave API

Crea una chiave API e ne restituisce il secret.

POST/api-keys

Richiede una chiave API full. Il secret in key viene restituito solo in questa risposta e quando rigeneri la chiave, quindi salvalo subito in un luogo sicuro. La chiave funziona anche come password SMTP. Per cosa consente ciascun permesso, vedi Autenticazione.

Parametri del corpo

namestringobbligatorio

Un nome che ti dice dove viene usata la chiave, ad esempio Production web app. Deve essere univoco tra le chiavi del workspace.

scopestringpredefinito: full

full per l’accesso a tutti gli endpoint, oppure sending solo per gli endpoint di invio. Non si può cambiare in seguito.

sending_domain_idstring

L’ID di un dominio di invio (dom_…) a cui limitare una chiave sending. La chiave potrà quindi inviare solo da indirizzi di quel dominio. Viene ignorato per le chiavi full.

Restituisce

Restituisce 201 con l’oggetto chiave API e il suo secret:

keystring

Il secret, che inizia con secret_. Usalo come token Bearer. Non viene più mostrato.

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"
  }
}

Recupera una chiave API

Recupera i dettagli di una chiave API. Il secret non è incluso.

GET/api-keys/{id}

Richiede una chiave API full. Le chiavi eliminate non vengono trovate.

Parametri di percorso

idstringobbligatorio

L’ID della chiave API (key_…) o il suo nome. Codifica nell’URL i nomi che contengono spazi.

Restituisce

Restituisce l’oggetto chiave API.

objectstring

Sempre api_key.

idstring

L’ID della chiave API.

namestring

Il nome della chiave.

scopestring

full o sending.

sending_domain_idstring | null

L’ID del dominio di invio a cui è limitata la chiave, oppure null.

last_used_atstring | null

Quando la chiave ha autenticato l’ultima richiesta, oppure null se non è stata usata da quando è stata creata o rigenerata.

created_atstring

Quando è stata creata la chiave.

updated_atstring

Quando la chiave è stata rinominata o rigenerata l’ultima volta.

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"
}

Elenca le chiavi API

Restituisce una pagina delle chiavi API del workspace, a partire dalla più recente.

GET/api-keys

Richiede una chiave API full. Le chiavi eliminate e i secret non sono inclusi. Controlla last_used_at per trovare le chiavi che non usi più.

Parametri di query

pageintegerpredefinito: 1

La pagina da restituire.

limitintegerpredefinito: 10

Chiavi per pagina, da 1 a 100.

searchstring

Corrispondenza sul nome della chiave, senza distinzione tra maiuscole e minuscole.

matchstringpredefinito: all

all o or. Come si combinano i filtri qui sotto.

orderstring

Una chiave di filtro per cui ordinare.

directionstring

asc o desc.

Filtri

Aggiungi i filtri nella forma key.condition=value, ad esempio scope.exact=sending. Vedi Filtri e ordinamento.

Chiave	Tipo	Note
`name`	string
`scope`	string	`full` o `sending`.
`type`	string	Tipo di credenziale. Le chiavi create nel pannello o con l’API sono `api`.
`created_at`	date

Ogni chiave di filtro è anche una chiave di ordinamento.

Restituisce

Restituisce un array data di oggetti chiave API con next_page_url e previous_page_url. Vedi Paginazione.

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
}

Aggiorna una chiave API

Rinomina una chiave API.

POST/api-keys/{id}

Richiede una chiave API full. Si può cambiare solo il nome. Per cambiare il permesso o la limitazione a un dominio, crea una nuova chiave ed elimina questa. Per sostituire il secret, rigenera la chiave.

Parametri di percorso

idstringobbligatorio

L’ID della chiave API o il suo nome attuale.

Parametri del corpo

namestringobbligatorio

Il nuovo nome. Deve essere univoco tra le chiavi del workspace.

Restituisce

Restituisce l’oggetto chiave API aggiornato.

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"
}

Rigenera una chiave API

Sostituisce il secret della chiave con uno nuovo. Il secret precedente smette subito di funzionare per le richieste API e per i nuovi accessi SMTP. La chiave mantiene ID, nome, permesso e dominio di invio, e last_used_at viene azzerato. Richiede una chiave API con il permesso full.

Il nuovo secret viene restituito solo in questa risposta. Salvalo subito, poi aggiorna ogni app e client SMTP che usava quello vecchio. Se rigeneri la chiave con cui fai questa richiesta, usa il nuovo secret per le richieste successive.

POST/api-keys/{id}/regenerate

Parametri di percorso

idstringobbligatorio

L’ID della chiave API (key_…) o il nome della chiave.

Restituisce

Restituisce l’oggetto chiave API con il nuovo secret in key.

keystring

Il nuovo secret, secret_ seguito da 32 lettere e cifre. Viene mostrato una sola volta.

scopestring

full o sending.

sending_domain_idstring | null

Il dominio di invio a cui è limitata una chiave sending, oppure null.

last_used_atnull

Sempre null dopo una rigenerazione.

Restituisce 404 se nessuna chiave API attiva corrisponde a 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"
}

Elimina una chiave API

Revoca una chiave API. Da questo momento le richieste e gli accessi SMTP con il suo secret non riescono.

DELETE/api-keys/{id}

Richiede una chiave API full. Puoi eliminare anche la chiave con cui stai chiamando, quindi assicurati prima che la tua integrazione abbia un’altra chiave. Una chiave eliminata non compare più in Elenca le chiavi API e il suo nome torna disponibile per una nuova chiave. Le email già inviate con la chiave non ne risentono.

Parametri di percorso

idstringobbligatorio

L’ID della chiave API o il suo nome.

Restituisce

objectstring

Sempre api_key.

idstring

L’ID della chiave eliminata.

namestring

Il nome della chiave.

deletedboolean

Sempre 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"
}