Chaves de API

Crie, liste, renomeie e revogue as chaves de API de um workspace.

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

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

Criar uma chave de API

Cria uma chave de API e retorna o segredo dela.

POST/api-keys

Requer uma chave de API com escopo full. O segredo em key é retornado apenas nesta resposta e quando você regenera a chave, então guarde-o com segurança imediatamente. A chave também funciona como senha SMTP. Consulte Autenticação para saber o que cada escopo permite.

Parâmetros do corpo

namestringobrigatório

Um nome que indique onde a chave é usada, como Production web app. Deve ser único entre as chaves do workspace.

scopestringpadrão: full

full para acesso a todos os endpoints, ou sending apenas para os endpoints de envio. Não pode ser alterado depois.

sending_domain_idstring

O ID de um domínio de envio (dom_…) ao qual restringir uma chave sending. A chave passa a enviar apenas de endereços desse domínio. Ignorado em chaves full.

Retorno

Retorna 201 com o objeto de chave de API e o segredo dela:

keystring

O segredo, que começa com secret_. Use-o como bearer token. Ele nunca é exibido de novo.

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

Obter uma chave de API

Obtém os detalhes de uma chave de API. O segredo não é incluído.

GET/api-keys/{id}

Requer uma chave de API com escopo full. Chaves excluídas não são encontradas.

Parâmetros de caminho

idstringobrigatório

O ID da chave de API (key_…) ou o nome dela. Codifique para URL os nomes com espaços.

Retorno

Retorna o objeto de chave de API.

objectstring

Sempre api_key.

idstring

O ID da chave de API.

namestring

O nome da chave.

scopestring

full ou sending.

sending_domain_idstring | null

O ID do domínio de envio ao qual a chave está restrita, ou null.

last_used_atstring | null

Quando a chave autenticou uma requisição pela última vez, ou null se ela não foi usada desde que foi criada ou regenerada.

created_atstring

Quando a chave foi criada.

updated_atstring

Quando a chave foi renomeada ou regenerada pela última vez.

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

Listar chaves de API

Retorna uma página das chaves de API do workspace, das mais recentes para as mais antigas.

GET/api-keys

Requer uma chave de API com escopo full. Chaves excluídas e segredos não são incluídos. Confira last_used_at para encontrar as chaves que você não usa mais.

Parâmetros de consulta

pageintegerpadrão: 1

A página a retornar.

limitintegerpadrão: 10

Chaves por página, de 1 a 100.

searchstring

Busca sem diferenciar maiúsculas de minúsculas no nome da chave.

matchstringpadrão: all

all ou or. Como os filtros abaixo se combinam.

orderstring

Uma chave de filtro pela qual ordenar.

directionstring

asc ou desc.

Filtros

Adicione filtros no formato key.condition=value, por exemplo scope.exact=sending. Consulte Filtragem.

Chave	Tipo	Observações
`name`	string
`scope`	string	`full` ou `sending`.
`type`	string	Tipo de credencial. As chaves criadas no painel ou pela API são `api`.
`created_at`	date

Todas as chaves também são chaves de ordenação.

Retorno

Retorna um array data de objetos de chave de API, com next_page_url e previous_page_url. Consulte Paginação.

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
}

Atualizar uma chave de API

Renomeia uma chave de API.

POST/api-keys/{id}

Requer uma chave de API com escopo full. Apenas o nome pode mudar. Para alterar o escopo ou a restrição de domínio, crie uma nova chave e exclua esta. Para substituir o segredo, regenere a chave.

Parâmetros de caminho

idstringobrigatório

O ID da chave de API ou o nome atual dela.

Parâmetros do corpo

namestringobrigatório

O novo nome. Deve ser único entre as chaves do workspace.

Retorno

Retorna o objeto de chave de API atualizado.

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

Regenerar uma chave de API

Substitui o segredo da chave por um novo. O segredo anterior para de funcionar imediatamente para requisições à API e novos logins SMTP. A chave mantém o ID, o nome, o escopo e o domínio de envio, e last_used_at é zerado. Requer uma chave de API com escopo full.

O novo segredo é retornado apenas nesta resposta. Guarde-o imediatamente e depois atualize todos os apps e clientes SMTP que usavam o antigo. Se você regenerar a própria chave que faz esta requisição, use o novo segredo nas requisições seguintes.

POST/api-keys/{id}/regenerate

Parâmetros de caminho

idstringobrigatório

O ID da chave de API (key_…) ou o nome da chave.

Retorno

Retorna o objeto de chave de API com o novo segredo em key.

keystring

O novo segredo, secret_ seguido de 32 letras e dígitos. Exibido uma única vez.

scopestring

full ou sending.

sending_domain_idstring | null

O domínio de envio ao qual uma chave sending está limitada, ou null.

last_used_atnull

Sempre null depois de uma regeneração.

Retorna 404 se nenhuma chave de API ativa corresponder 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"
}

Excluir uma chave de API

Revoga uma chave de API. A partir de agora, requisições e logins SMTP com o segredo dela falham.

DELETE/api-keys/{id}

Requer uma chave de API com escopo full. Você pode excluir a própria chave com que está fazendo a chamada, então garanta antes que a sua integração tenha outra chave. Uma chave excluída deixa de aparecer em Listar chaves de API, e o nome dela fica livre para uma nova chave. Os e-mails já enviados com a chave não são afetados.

Parâmetros de caminho

idstringobrigatório

O ID da chave de API ou o nome dela.

Retorno

objectstring

Sempre api_key.

idstring

O ID da chave excluída.

namestring

O nome da chave.

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