Appearance
API Keys
Fresh 🌱AgentMail REST API reference for API Keys. Base URL
https://api.agentmail.to/v0. Authenticate withAuthorization: Bearer <API_KEY>.
Create API Key
POST https://api.agentmail.to/v0/api-keys Content-Type: application/json
CLI:
bash
agentmail api-keys create --name "My Key"OpenAPI Specification
yaml
openapi: 3.1.0
info:
title: api
version: 1.0.0
paths:
/v0/api-keys:
post:
operationId: create
summary: Create API Key
description: |-
**CLI:**
```bash
agentmail api-keys create --name "My Key"
```
tags:
- subpackage_api-keys
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_api-keys:CreateApiKeyResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_api-keys:CreateApiKeyRequest'
servers:
- url: https://api.agentmail.to
description: prod
- url: https://x402.api.agentmail.to
description: prod-x402
- url: https://mpp.api.agentmail.to
description: prod-mpp
- url: https://api.agentmail.eu
description: eu-prod
components:
schemas:
type_api-keys:Name:
type: string
description: Name of api key.
title: Name
type_api-keys:ApiKeyPermissions:
type: object
properties:
inbox_read:
type: boolean
description: Read inbox details.
inbox_create:
type: boolean
description: Create new inboxes.
inbox_update:
type: boolean
description: Update inbox settings.
inbox_delete:
type: boolean
description: Delete inboxes.
thread_read:
type: boolean
description: Read threads.
thread_delete:
type: boolean
description: Delete threads.
message_read:
type: boolean
description: Read messages.
message_send:
type: boolean
description: Send messages.
message_update:
type: boolean
description: Update message labels.
label_spam_read:
type: boolean
description: Access messages labeled spam.
label_blocked_read:
type: boolean
description: Access messages labeled blocked.
label_trash_read:
type: boolean
description: Access messages labeled trash.
draft_read:
type: boolean
description: Read drafts.
draft_create:
type: boolean
description: Create drafts.
draft_update:
type: boolean
description: Update drafts.
draft_delete:
type: boolean
description: Delete drafts.
draft_send:
type: boolean
description: Send drafts.
webhook_read:
type: boolean
description: Read webhook configurations.
webhook_create:
type: boolean
description: Create webhooks.
webhook_update:
type: boolean
description: Update webhooks.
webhook_delete:
type: boolean
description: Delete webhooks.
domain_read:
type: boolean
description: Read domain details.
domain_create:
type: boolean
description: Create domains.
domain_update:
type: boolean
description: Update domains.
domain_delete:
type: boolean
description: Delete domains.
list_entry_read:
type: boolean
description: Read list entries.
list_entry_create:
type: boolean
description: Create list entries.
list_entry_delete:
type: boolean
description: Delete list entries.
metrics_read:
type: boolean
description: Read metrics.
api_key_read:
type: boolean
description: Read API keys.
api_key_create:
type: boolean
description: Create API keys.
api_key_delete:
type: boolean
description: Delete API keys.
pod_read:
type: boolean
description: Read pods.
pod_create:
type: boolean
description: Create pods.
pod_delete:
type: boolean
description: Delete pods.
description: >-
Granular permissions for the API key. When ommitted all permissions are
granted. Otherwise, only permissions set to true are granted.
title: ApiKeyPermissions
type_api-keys:CreateApiKeyRequest:
type: object
properties:
name:
$ref: '#/components/schemas/type_api-keys:Name'
permissions:
$ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
title: CreateApiKeyRequest
type_api-keys:ApiKeyId:
type: string
description: ID of api key.
title: ApiKeyId
type_api-keys:Prefix:
type: string
description: Prefix of api key.
title: Prefix
type_api-keys:CreatedAt:
type: string
format: date-time
description: Time at which api key was created.
title: CreatedAt
type_api-keys:CreateApiKeyResponse:
type: object
properties:
api_key_id:
$ref: '#/components/schemas/type_api-keys:ApiKeyId'
api_key:
type: string
description: API key.
prefix:
$ref: '#/components/schemas/type_api-keys:Prefix'
name:
$ref: '#/components/schemas/type_api-keys:Name'
pod_id:
type: string
description: Pod ID the api key is scoped to.
inbox_id:
type: string
description: Inbox ID the api key is scoped to.
permissions:
$ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
created_at:
$ref: '#/components/schemas/type_api-keys:CreatedAt'
required:
- api_key_id
- api_key
- prefix
- name
- created_at
title: CreateApiKeyResponse
type_:ErrorName:
type: string
description: Name of error.
title: ErrorName
type_:ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type_:ErrorName'
errors:
description: Validation errors.
required:
- name
- errors
title: ValidationErrorResponse
securitySchemes:
Bearer:
type: http
scheme: bearerExamples
Request
json
{}Response
json
{
"api_key_id": "api_key_id",
"api_key": "api_key",
"prefix": "prefix",
"name": "name",
"created_at": "2024-01-15T09:30:00Z",
"pod_id": "pod_id",
"inbox_id": "inbox_id",
"permissions": {
"inbox_read": true,
"inbox_create": true,
"inbox_update": true,
"inbox_delete": true,
"thread_read": true,
"thread_delete": true,
"message_read": true,
"message_send": true,
"message_update": true,
"label_spam_read": true,
"label_blocked_read": true,
"label_trash_read": true,
"draft_read": true,
"draft_create": true,
"draft_update": true,
"draft_delete": true,
"draft_send": true,
"webhook_read": true,
"webhook_create": true,
"webhook_update": true,
"webhook_delete": true,
"domain_read": true,
"domain_create": true,
"domain_update": true,
"domain_delete": true,
"list_entry_read": true,
"list_entry_create": true,
"list_entry_delete": true,
"metrics_read": true,
"api_key_read": true,
"api_key_create": true,
"api_key_delete": true,
"pod_read": true,
"pod_create": true,
"pod_delete": true
}
}SDK Code
typescript
import { AgentMailClient } from "agentmail";
async function main() {
const client = new AgentMailClient({
apiKey: "YOUR_TOKEN_HERE",
});
await client.apiKeys.create({});
}
main();python
from agentmail import AgentMail
client = AgentMail(
api_key="YOUR_TOKEN_HERE",
)
client.api_keys.create()go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.agentmail.to/v0/api-keys"
payload := strings.NewReader("{}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <api_key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}ruby
require 'uri'
require 'net/http'
url = URI("https://api.agentmail.to/v0/api-keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{}"
response = http.request(request)
puts response.read_bodyjava
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/api-keys")
.header("Authorization", "Bearer <api_key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();php
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.agentmail.to/v0/api-keys', [
'body' => '{}',
'headers' => [
'Authorization' => 'Bearer <api_key>',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();csharp
using RestSharp;
var client = new RestClient("https://api.agentmail.to/v0/api-keys");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);swift
import Foundation
let headers = [
"Authorization": "Bearer <api_key>",
"Content-Type": "application/json"
]
let parameters = [] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/api-keys")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()List API Keys
GET https://api.agentmail.to/v0/api-keys
CLI:
bash
agentmail api-keys listOpenAPI Specification
yaml
openapi: 3.1.0
info:
title: api
version: 1.0.0
paths:
/v0/api-keys:
get:
operationId: list
summary: List API Keys
description: |-
**CLI:**
```bash
agentmail api-keys list
```
tags:
- subpackage_api-keys
parameters:
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/type_:PageToken'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/type_:Ascending'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_api-keys:ListApiKeysResponse'
servers:
- url: https://api.agentmail.to
description: prod
- url: https://x402.api.agentmail.to
description: prod-x402
- url: https://mpp.api.agentmail.to
description: prod-mpp
- url: https://api.agentmail.eu
description: eu-prod
components:
schemas:
type_:Limit:
type: integer
description: Limit of number of items returned.
title: Limit
type_:PageToken:
type: string
description: Page token for pagination.
title: PageToken
type_:Ascending:
type: boolean
description: Sort in ascending temporal order.
title: Ascending
type_:Count:
type: integer
description: Number of items returned.
title: Count
type_api-keys:ApiKeyId:
type: string
description: ID of api key.
title: ApiKeyId
type_api-keys:Prefix:
type: string
description: Prefix of api key.
title: Prefix
type_api-keys:Name:
type: string
description: Name of api key.
title: Name
type_api-keys:ApiKeyPermissions:
type: object
properties:
inbox_read:
type: boolean
description: Read inbox details.
inbox_create:
type: boolean
description: Create new inboxes.
inbox_update:
type: boolean
description: Update inbox settings.
inbox_delete:
type: boolean
description: Delete inboxes.
thread_read:
type: boolean
description: Read threads.
thread_delete:
type: boolean
description: Delete threads.
message_read:
type: boolean
description: Read messages.
message_send:
type: boolean
description: Send messages.
message_update:
type: boolean
description: Update message labels.
label_spam_read:
type: boolean
description: Access messages labeled spam.
label_blocked_read:
type: boolean
description: Access messages labeled blocked.
label_trash_read:
type: boolean
description: Access messages labeled trash.
draft_read:
type: boolean
description: Read drafts.
draft_create:
type: boolean
description: Create drafts.
draft_update:
type: boolean
description: Update drafts.
draft_delete:
type: boolean
description: Delete drafts.
draft_send:
type: boolean
description: Send drafts.
webhook_read:
type: boolean
description: Read webhook configurations.
webhook_create:
type: boolean
description: Create webhooks.
webhook_update:
type: boolean
description: Update webhooks.
webhook_delete:
type: boolean
description: Delete webhooks.
domain_read:
type: boolean
description: Read domain details.
domain_create:
type: boolean
description: Create domains.
domain_update:
type: boolean
description: Update domains.
domain_delete:
type: boolean
description: Delete domains.
list_entry_read:
type: boolean
description: Read list entries.
list_entry_create:
type: boolean
description: Create list entries.
list_entry_delete:
type: boolean
description: Delete list entries.
metrics_read:
type: boolean
description: Read metrics.
api_key_read:
type: boolean
description: Read API keys.
api_key_create:
type: boolean
description: Create API keys.
api_key_delete:
type: boolean
description: Delete API keys.
pod_read:
type: boolean
description: Read pods.
pod_create:
type: boolean
description: Create pods.
pod_delete:
type: boolean
description: Delete pods.
description: >-
Granular permissions for the API key. When ommitted all permissions are
granted. Otherwise, only permissions set to true are granted.
title: ApiKeyPermissions
type_api-keys:CreatedAt:
type: string
format: date-time
description: Time at which api key was created.
title: CreatedAt
type_api-keys:ApiKey:
type: object
properties:
api_key_id:
$ref: '#/components/schemas/type_api-keys:ApiKeyId'
prefix:
$ref: '#/components/schemas/type_api-keys:Prefix'
name:
$ref: '#/components/schemas/type_api-keys:Name'
pod_id:
type: string
description: >-
Pod ID the api key is scoped to. If set, the key can only access
resources within this pod.
inbox_id:
type: string
description: >-
Inbox ID the api key is scoped to. If set, the key can only access
resources within this inbox.
used_at:
type: string
format: date-time
description: Time at which api key was last used.
permissions:
$ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
created_at:
$ref: '#/components/schemas/type_api-keys:CreatedAt'
required:
- api_key_id
- prefix
- name
- created_at
title: ApiKey
type_api-keys:ListApiKeysResponse:
type: object
properties:
count:
$ref: '#/components/schemas/type_:Count'
next_page_token:
$ref: '#/components/schemas/type_:PageToken'
api_keys:
type: array
items:
$ref: '#/components/schemas/type_api-keys:ApiKey'
description: Ordered by `created_at` descending.
required:
- count
- api_keys
title: ListApiKeysResponse
securitySchemes:
Bearer:
type: http
scheme: bearerExamples
Response
json
{
"count": 1,
"api_keys": [
{
"api_key_id": "api_key_id",
"prefix": "prefix",
"name": "name",
"created_at": "2024-01-15T09:30:00Z",
"pod_id": "pod_id",
"inbox_id": "inbox_id",
"used_at": "2024-01-15T09:30:00Z",
"permissions": {
"inbox_read": true,
"inbox_create": true,
"inbox_update": true,
"inbox_delete": true,
"thread_read": true,
"thread_delete": true,
"message_read": true,
"message_send": true,
"message_update": true,
"label_spam_read": true,
"label_blocked_read": true,
"label_trash_read": true,
"draft_read": true,
"draft_create": true,
"draft_update": true,
"draft_delete": true,
"draft_send": true,
"webhook_read": true,
"webhook_create": true,
"webhook_update": true,
"webhook_delete": true,
"domain_read": true,
"domain_create": true,
"domain_update": true,
"domain_delete": true,
"list_entry_read": true,
"list_entry_create": true,
"list_entry_delete": true,
"metrics_read": true,
"api_key_read": true,
"api_key_create": true,
"api_key_delete": true,
"pod_read": true,
"pod_create": true,
"pod_delete": true
}
},
{
"api_key_id": "api_key_id",
"prefix": "prefix",
"name": "name",
"created_at": "2024-01-15T09:30:00Z",
"pod_id": "pod_id",
"inbox_id": "inbox_id",
"used_at": "2024-01-15T09:30:00Z",
"permissions": {
"inbox_read": true,
"inbox_create": true,
"inbox_update": true,
"inbox_delete": true,
"thread_read": true,
"thread_delete": true,
"message_read": true,
"message_send": true,
"message_update": true,
"label_spam_read": true,
"label_blocked_read": true,
"label_trash_read": true,
"draft_read": true,
"draft_create": true,
"draft_update": true,
"draft_delete": true,
"draft_send": true,
"webhook_read": true,
"webhook_create": true,
"webhook_update": true,
"webhook_delete": true,
"domain_read": true,
"domain_create": true,
"domain_update": true,
"domain_delete": true,
"list_entry_read": true,
"list_entry_create": true,
"list_entry_delete": true,
"metrics_read": true,
"api_key_read": true,
"api_key_create": true,
"api_key_delete": true,
"pod_read": true,
"pod_create": true,
"pod_delete": true
}
}
],
"next_page_token": "next_page_token"
}SDK Code
typescript
import { AgentMailClient } from "agentmail";
async function main() {
const client = new AgentMailClient({
apiKey: "YOUR_TOKEN_HERE",
});
await client.apiKeys.list({});
}
main();python
from agentmail import AgentMail
client = AgentMail(
api_key="YOUR_TOKEN_HERE",
)
client.api_keys.list()go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.agentmail.to/v0/api-keys"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <api_key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}ruby
require 'uri'
require 'net/http'
url = URI("https://api.agentmail.to/v0/api-keys")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <api_key>'
response = http.request(request)
puts response.read_bodyjava
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/api-keys")
.header("Authorization", "Bearer <api_key>")
.asString();php
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.agentmail.to/v0/api-keys', [
'headers' => [
'Authorization' => 'Bearer <api_key>',
],
]);
echo $response->getBody();csharp
using RestSharp;
var client = new RestClient("https://api.agentmail.to/v0/api-keys");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);swift
import Foundation
let headers = ["Authorization": "Bearer <api_key>"]
let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/api-keys")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()Delete API Key
DELETE https://api.agentmail.to/v0/api-keys/{api_key_id}
CLI:
bash
agentmail api-keys delete --api-key-id <api_key_id>OpenAPI Specification
yaml
openapi: 3.1.0
info:
title: api
version: 1.0.0
paths:
/v0/api-keys/{api_key_id}:
delete:
operationId: delete
summary: Delete API Key
description: |-
**CLI:**
```bash
agentmail api-keys delete --api-key-id <api_key_id>
```
tags:
- subpackage_api-keys
parameters:
- name: api_key_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_api-keys:ApiKeyId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
servers:
- url: https://api.agentmail.to
description: prod
- url: https://x402.api.agentmail.to
description: prod-x402
- url: https://mpp.api.agentmail.to
description: prod-mpp
- url: https://api.agentmail.eu
description: eu-prod
components:
schemas:
type_api-keys:ApiKeyId:
type: string
description: ID of api key.
title: ApiKeyId
type_:ErrorName:
type: string
description: Name of error.
title: ErrorName
type_:ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
type_:ErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type_:ErrorName'
message:
$ref: '#/components/schemas/type_:ErrorMessage'
required:
- name
- message
title: ErrorResponse
securitySchemes:
Bearer:
type: http
scheme: bearerExamples
SDK Code
typescript
import { AgentMailClient } from "agentmail";
async function main() {
const client = new AgentMailClient({
apiKey: "YOUR_TOKEN_HERE",
});
await client.apiKeys.delete("api_key_id");
}
main();python
from agentmail import AgentMail
client = AgentMail(
api_key="YOUR_TOKEN_HERE",
)
client.api_keys.delete(
api_key_id="api_key_id",
)go
package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.agentmail.to/v0/api-keys/api_key_id"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("Authorization", "Bearer <api_key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}ruby
require 'uri'
require 'net/http'
url = URI("https://api.agentmail.to/v0/api-keys/api_key_id")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <api_key>'
response = http.request(request)
puts response.read_bodyjava
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.delete("https://api.agentmail.to/v0/api-keys/api_key_id")
.header("Authorization", "Bearer <api_key>")
.asString();php
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.agentmail.to/v0/api-keys/api_key_id', [
'headers' => [
'Authorization' => 'Bearer <api_key>',
],
]);
echo $response->getBody();csharp
using RestSharp;
var client = new RestClient("https://api.agentmail.to/v0/api-keys/api_key_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer <api_key>");
IRestResponse response = client.Execute(request);swift
import Foundation
let headers = ["Authorization": "Bearer <api_key>"]
let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/api-keys/api_key_id")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()