# API keys API

> Create, list, rename and revoke the API keys of a workspace.

Base URL: `https://api.emailit.com/v2`. Authenticate with `Authorization: Bearer <API key>`.

## Create an API key — POST /api-keys

> Create a full or sending API key for the workspace, optionally restricted to one sending domain. The secret is returned only once.

# Create an API key

Creates an API key and returns its secret.

`POST /api-keys`

Requires a `full` API key. The secret in `key` is returned only in this response and when you [regenerate](/docs/api-reference/api-keys/regenerate/) the key, so store it securely right away. The key also works as an SMTP password. See [Authentication](/docs/api-reference/authentication/) for what each scope allows.

## Body parameters

- `name` (string, required): A name that tells you where the key is used, such as `Production web app`. Must be unique among the workspace's keys.

- `scope` (string): `full` for access to every endpoint, or `sending` for the send endpoints only. Can't be changed later.

- `sending_domain_id` (string): The ID of a sending domain (`dom_…`) to restrict a `sending` key to. The key can then only send from addresses on that domain. Ignored for `full` keys.

## Returns

Returns `201` with the [API key object](/docs/api-reference/api-keys/get/) and its secret:

- `key` (string): The secret, starting with `secret_`. Use it as the Bearer token. It's never shown again.

**Request** `POST /api-keys`

**Node.js**

```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**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

```go
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**

```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**

```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()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

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

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

```bash
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"
  }'
```

**cURL**

```bash
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"
  }'
```

**Node.js**

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

**Python**

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

**201**

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

**400**

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

**409**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/create/

## Retrieve an API key — GET /api-keys/{id}

> Retrieve an API key by ID or name with its scope, domain restriction and when it was last used. The secret itself is never returned.

# Retrieve an API key

Retrieves an API key's details. The secret isn't included.

`GET /api-keys/{id}`

Requires a `full` API key. Deleted keys aren't found.

## Path parameters

- `id` (string, required): The API key ID (`key_…`) or its name. URL-encode names with spaces.

## Returns

Returns the API key object.

- `object` (string): Always `api_key`.

- `id` (string): The API key ID.

- `name` (string): The key's name.

- `scope` (string): `full` or `sending`.

- `sending_domain_id` (string | null): The ID of the sending domain the key is restricted to, or `null`.

- `last_used_at` (string | null): When the key last authenticated a request, or `null` if it hasn't been used since it was created or regenerated.

- `created_at` (string): When the key was created.

- `updated_at` (string): When the key was last renamed or regenerated.

**Request** `GET /api-keys/{id}`

**Node.js**

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

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

**Python**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

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

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

**Rust**

```rust
use emailit::Emailit;

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

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

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

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

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

**404**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/get/

## List API keys — GET /api-keys

> List the API keys of a workspace with their scope, domain restriction and last use, newest first. Secrets are never included.

# List API keys

Returns a page of the workspace's API keys, newest first.

`GET /api-keys`

Requires a `full` API key. Deleted keys and secrets aren't included. Check `last_used_at` to find keys you no longer use.

## Query parameters

- `page` (integer): The page to return.

- `limit` (integer): Keys per page, from 1 to 100.

- `search` (string): Case-insensitive match on the key name.

- `match` (string): `all` or `or`. How the filters below combine.

- `order` (string): A filter key to sort by.

- `direction` (string): `asc` or `desc`.

## Filters

Add filters as `key.condition=value`, for example `scope.exact=sending`. See [Filtering](/docs/api-reference/filtering/).

| Key | Type | Notes |
| --- | --- | --- |
| `name` | string | |
| `scope` | string | `full` or `sending`. |
| `type` | string | Credential type. Keys created in the dashboard or API are `api`. |
| `created_at` | date | |

Every key is also a sort key.

## Returns

Returns a `data` array of [API key objects](/docs/api-reference/api-keys/get/) with `next_page_url` and `previous_page_url`. See [Pagination](/docs/api-reference/pagination/).

**Request** `GET /api-keys`

**Node.js**

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

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

**Python**

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

api_keys = client.api_keys.list()
```

**PHP**

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

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

**Ruby**

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

api_keys = client.api_keys.list
```

**Go**

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

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

**Rust**

```rust
use emailit::Emailit;

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

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

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

var apiKeys = emailit.ApiKeys.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/list/

## Update an API key — POST /api-keys/{id}

> Rename an API key. The secret, scope and domain restriction stay the same; to change them, create a new key or regenerate the secret.

# Update an API key

Renames an API key.

`POST /api-keys/{id}`

Requires a `full` API key. Only the name can change. To change the scope or domain restriction, [create a new key](/docs/api-reference/api-keys/create/) and delete this one. To replace the secret, [regenerate](/docs/api-reference/api-keys/regenerate/) it.

## Path parameters

- `id` (string, required): The API key ID or its current name.

## Body parameters

- `name` (string, required): The new name. Must be unique among the workspace's keys.

## Returns

Returns the updated [API key object](/docs/api-reference/api-keys/get/).

**Request** `POST /api-keys/{id}`

**Node.js**

```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**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

```go
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**

```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**

```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()
);
```

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

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

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

```bash
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)"
  }'
```

**200**

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

**404**

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

**409**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/update/

## Regenerate an API key — POST /api-keys/{id}/regenerate

> Issue a new secret for an existing API key. The old secret stops working at once; ID, name, scope and domain stay the same.

# Regenerate an API key

Replaces the key's secret with a new one. The previous secret stops working immediately for API requests and new SMTP logins. The key keeps its ID, name, scope and sending domain, and `last_used_at` is reset. Requires an API key with the `full` scope.

The new secret is returned only in this response. Store it right away, then update every app and SMTP client that used the old one. If you regenerate the key that makes this request, use the new secret for later requests.

`POST /api-keys/{id}/regenerate`

## Path parameters

- `id` (string, required): The API key ID (`key_…`) or the key's name.

## Returns

Returns the API key object with the new secret in `key`.

- `key` (string): The new secret, `secret_` followed by 32 letters and digits. Shown only once.

- `scope` (string): `full` or `sending`.

- `sending_domain_id` (string | null): The sending domain a `sending` key is limited to, or `null`.

- `last_used_at` (null): Always `null` after a regeneration.

Returns `404` if no active API key matches `id`.

**Request** `POST /api-keys/{id}/regenerate`

**cURL**

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

**Node.js**

```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**

```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**

```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'];
```

**200**

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

**404**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/regenerate/

## Delete an API key — DELETE /api-keys/{id}

> Revoke an API key so it stops working immediately for API and SMTP requests. The delete can't be undone.

# Delete an API key

Revokes an API key. Requests and SMTP logins with its secret fail from now on.

`DELETE /api-keys/{id}`

Requires a `full` API key. You can delete the key you're calling with, so make sure your integration has another key first. A deleted key no longer appears in [List API keys](/docs/api-reference/api-keys/list/), and its name becomes free for a new key. Emails already sent with the key are unaffected.

## Path parameters

- `id` (string, required): The API key ID or its name.

## Returns

- `object` (string): Always `api_key`.

- `id` (string): The ID of the deleted key.

- `name` (string): The key's name.

- `deleted` (boolean): Always `true`.

**Request** `DELETE /api-keys/{id}`

**Node.js**

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

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

**Python**

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

client.api_keys.delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1")
```

**PHP**

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

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

**Ruby**

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

client.api_keys.delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1")
```

**Go**

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

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

**Rust**

```rust
use emailit::Emailit;

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

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

**Java**

```java
import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

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

**.NET**

```csharp
using Emailit;

var emailit = new EmailitClient("your_api_key");

emailit.ApiKeys.Delete("key_4Kw6E8FodRivXbJlwPdn79gOxi1");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

**404**

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

---
Source: https://emailit.com/docs/api-reference/api-keys/delete/