Inboxes

Fresh 🌱

AgentMail REST API reference for Inboxes. Base URL https://api.agentmail.to/v0. Authenticate with Authorization: Bearer <API_KEY>.

Inboxes Overview

GET https://api.agentmail.to/v0/inboxes

CLI:

bash

agentmail inboxes list

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes:
    get:
      operationId: list
      summary: List Inboxes
      description: |-
        **CLI:**
        ```bash
        agentmail inboxes list
        ```
      tags:
        - subpackage_inboxes
      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_inboxes:ListInboxesResponse'
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_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_inboxes:Email:
      type: string
      description: Email address of the inbox.
      title: Email
    type_inboxes:DisplayName:
      type: string
      description: 'Display name: `Display Name <username@domain.com>`.'
      title: DisplayName
    type_inboxes:ClientId:
      type: string
      description: Client ID of inbox.
      title: ClientId
    type_inboxes:MetadataValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: A metadata value. May be a string, number, or boolean.
      title: MetadataValue
    type_inboxes:Metadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_inboxes:MetadataValue'
      description: >-
        Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and

        string values are each limited to 256 characters. When updating
        metadata,

        send a key with a null value to remove that key.
      title: Metadata
    type_inboxes:Inbox:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        email:
          $ref: '#/components/schemas/type_inboxes:Email'
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata attached to the inbox.
        updated_at:
          type: string
          format: date-time
          description: Time at which inbox was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which inbox was created.
      required:
        - pod_id
        - inbox_id
        - email
        - updated_at
        - created_at
      title: Inbox
    type_inboxes:ListInboxesResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        inboxes:
          type: array
          items:
            $ref: '#/components/schemas/type_inboxes:Inbox'
          description: Ordered by `created_at` descending.
      required:
        - count
        - inboxes
      title: ListInboxesResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Response

json

{
  "count": 1,
  "inboxes": [
    {
      "pod_id": "pod_id",
      "inbox_id": "inbox_id",
      "email": "email",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "display_name": "display_name",
      "client_id": "client_id",
      "metadata": {
        "metadata": "metadata"
      }
    },
    {
      "pod_id": "pod_id",
      "inbox_id": "inbox_id",
      "email": "email",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "display_name": "display_name",
      "client_id": "client_id",
      "metadata": {
        "metadata": "metadata"
      }
    }
  ],
  "limit": 1,
  "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.inboxes.list({});
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.list()

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes"

	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/inboxes")

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_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/inboxes")
  .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/inboxes', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes");
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/inboxes")! 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()

Create Inbox

POST https://api.agentmail.to/v0/inboxes Content-Type: application/json

CLI:

bash

agentmail inboxes create --display-name "My Agent" --username myagent --domain agentmail.to

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes:
    post:
      operationId: create
      summary: Create Inbox
      description: >-
        **CLI:**

        ```bash

        agentmail inboxes create --display-name "My Agent" --username myagent
        --domain agentmail.to

        ```
      tags:
        - subpackage_inboxes
      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_inboxes:Inbox'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ValidationErrorResponse'
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_inboxes:CreateInboxRequest'
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_inboxes:DisplayName:
      type: string
      description: 'Display name: `Display Name <username@domain.com>`.'
      title: DisplayName
    type_inboxes:ClientId:
      type: string
      description: Client ID of inbox.
      title: ClientId
    type_inboxes:MetadataValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: A metadata value. May be a string, number, or boolean.
      title: MetadataValue
    type_inboxes:Metadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_inboxes:MetadataValue'
      description: >-
        Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and

        string values are each limited to 256 characters. When updating
        metadata,

        send a key with a null value to remove that key.
      title: Metadata
    type_inboxes:CreateInboxRequest:
      type: object
      properties:
        username:
          type: string
          description: Username of address. Randomly generated if not specified.
        domain:
          type: string
          description: >-
            Domain of address. Must be a verified domain, or any subdomain of a

            verified domain that has subdomains enabled (e.g.,
            `bot.example.com`).

            Defaults to `agentmail.to`.
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata to attach to the inbox.
      title: CreateInboxRequest
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_inboxes:Email:
      type: string
      description: Email address of the inbox.
      title: Email
    type_inboxes:Inbox:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        email:
          $ref: '#/components/schemas/type_inboxes:Email'
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata attached to the inbox.
        updated_at:
          type: string
          format: date-time
          description: Time at which inbox was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which inbox was created.
      required:
        - pod_id
        - inbox_id
        - email
        - updated_at
        - created_at
      title: Inbox
    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
    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: bearer

Examples

Request

json

undefined

Response

json

{
  "pod_id": "pod_id",
  "inbox_id": "inbox_id",
  "email": "email",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "display_name": "display_name",
  "client_id": "client_id",
  "metadata": {
    "metadata": "metadata"
  }
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.create();
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.create()

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes"

	req, _ := http.NewRequest("POST", url, nil)

	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/inboxes")

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'

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.agentmail.to/v0/inboxes")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .asString();

php

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.agentmail.to/v0/inboxes', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

swift

import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()

Get Inbox

GET https://api.agentmail.to/v0/inboxes/{inbox_id}

CLI:

bash

agentmail inboxes get --inbox-id <inbox_id>

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}:
    get:
      operationId: get
      summary: Get Inbox
      description: |-
        **CLI:**
        ```bash
        agentmail inboxes get --inbox-id <inbox_id>
        ```
      tags:
        - subpackage_inboxes
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - 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_inboxes:Inbox'
        '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_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_inboxes:Email:
      type: string
      description: Email address of the inbox.
      title: Email
    type_inboxes:DisplayName:
      type: string
      description: 'Display name: `Display Name <username@domain.com>`.'
      title: DisplayName
    type_inboxes:ClientId:
      type: string
      description: Client ID of inbox.
      title: ClientId
    type_inboxes:MetadataValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: A metadata value. May be a string, number, or boolean.
      title: MetadataValue
    type_inboxes:Metadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_inboxes:MetadataValue'
      description: >-
        Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and

        string values are each limited to 256 characters. When updating
        metadata,

        send a key with a null value to remove that key.
      title: Metadata
    type_inboxes:Inbox:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        email:
          $ref: '#/components/schemas/type_inboxes:Email'
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata attached to the inbox.
        updated_at:
          type: string
          format: date-time
          description: Time at which inbox was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which inbox was created.
      required:
        - pod_id
        - inbox_id
        - email
        - updated_at
        - created_at
      title: Inbox
    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: bearer

Examples

Response

json

{
  "pod_id": "pod_id",
  "inbox_id": "inbox_id",
  "email": "email",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "display_name": "display_name",
  "client_id": "client_id",
  "metadata": {
    "metadata": "metadata"
  }
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.get("inbox_id");
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.get(
    inbox_id="inbox_id",
)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id"

	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/inboxes/inbox_id")

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_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/inboxes/inbox_id")
  .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/inboxes/inbox_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_id");
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/inboxes/inbox_id")! 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()

List Inboxes

GET https://api.agentmail.to/v0/inboxes

CLI:

bash

agentmail inboxes list

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes:
    get:
      operationId: list
      summary: List Inboxes
      description: |-
        **CLI:**
        ```bash
        agentmail inboxes list
        ```
      tags:
        - subpackage_inboxes
      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_inboxes:ListInboxesResponse'
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_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_inboxes:Email:
      type: string
      description: Email address of the inbox.
      title: Email
    type_inboxes:DisplayName:
      type: string
      description: 'Display name: `Display Name <username@domain.com>`.'
      title: DisplayName
    type_inboxes:ClientId:
      type: string
      description: Client ID of inbox.
      title: ClientId
    type_inboxes:MetadataValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: A metadata value. May be a string, number, or boolean.
      title: MetadataValue
    type_inboxes:Metadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_inboxes:MetadataValue'
      description: >-
        Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and

        string values are each limited to 256 characters. When updating
        metadata,

        send a key with a null value to remove that key.
      title: Metadata
    type_inboxes:Inbox:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        email:
          $ref: '#/components/schemas/type_inboxes:Email'
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata attached to the inbox.
        updated_at:
          type: string
          format: date-time
          description: Time at which inbox was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which inbox was created.
      required:
        - pod_id
        - inbox_id
        - email
        - updated_at
        - created_at
      title: Inbox
    type_inboxes:ListInboxesResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        inboxes:
          type: array
          items:
            $ref: '#/components/schemas/type_inboxes:Inbox'
          description: Ordered by `created_at` descending.
      required:
        - count
        - inboxes
      title: ListInboxesResponse
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

Examples

Response

json

{
  "count": 1,
  "inboxes": [
    {
      "pod_id": "pod_id",
      "inbox_id": "inbox_id",
      "email": "email",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "display_name": "display_name",
      "client_id": "client_id",
      "metadata": {
        "metadata": "metadata"
      }
    },
    {
      "pod_id": "pod_id",
      "inbox_id": "inbox_id",
      "email": "email",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "display_name": "display_name",
      "client_id": "client_id",
      "metadata": {
        "metadata": "metadata"
      }
    }
  ],
  "limit": 1,
  "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.inboxes.list({});
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.list()

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes"

	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/inboxes")

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_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/inboxes")
  .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/inboxes', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes");
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/inboxes")! 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()

Update Inbox

PATCH https://api.agentmail.to/v0/inboxes/{inbox_id} Content-Type: application/json

CLI:

bash

agentmail inboxes update --inbox-id <inbox_id> --display-name "Updated Name"

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}:
    patch:
      operationId: update
      summary: Update Inbox
      description: >-
        **CLI:**

        ```bash

        agentmail inboxes update --inbox-id <inbox_id> --display-name "Updated
        Name"

        ```
      tags:
        - subpackage_inboxes
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - 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_inboxes:Inbox'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ValidationErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:ErrorResponse'
      requestBody:
        description: >-
          Expects an object; provide at least one of `display_name` or
          `metadata`.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_inboxes:UpdateInboxRequest'
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_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_inboxes:DisplayName:
      type: string
      description: 'Display name: `Display Name <username@domain.com>`.'
      title: DisplayName
    type_inboxes:MetadataValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: A metadata value. May be a string, number, or boolean.
      title: MetadataValue
    type_inboxes:UpdateMetadata:
      type: object
      additionalProperties:
        oneOf:
          - $ref: '#/components/schemas/type_inboxes:MetadataValue'
          - type: 'null'
      description: |-
        Custom key-value pairs to merge into the inbox's existing metadata. A
        value may be a string, number, boolean, or null. Setting a key to null
        removes it. Up to 256 keys; keys and string values are each limited to
        256 characters.
      title: UpdateMetadata
    type_inboxes:UpdateInboxRequest:
      type: object
      properties:
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        metadata:
          oneOf:
            - $ref: '#/components/schemas/type_inboxes:UpdateMetadata'
            - type: 'null'
          description: >-
            Metadata to merge into the inbox's existing metadata. Keys you
            include

            are added or overwritten; keys you omit are left unchanged. To
            remove a

            single key, send it with a null value. To clear all metadata, send

            `metadata` as null. Sending an empty object is rejected; use null to

            clear. Each update must include at least one of `display_name` or

            `metadata`.
      title: UpdateInboxRequest
    type_pods:PodId:
      type: string
      description: ID of pod.
      title: PodId
    type_inboxes:Email:
      type: string
      description: Email address of the inbox.
      title: Email
    type_inboxes:ClientId:
      type: string
      description: Client ID of inbox.
      title: ClientId
    type_inboxes:Metadata:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/type_inboxes:MetadataValue'
      description: >-
        Custom key-value pairs attached to the inbox. Up to 256 keys. Keys and

        string values are each limited to 256 characters. When updating
        metadata,

        send a key with a null value to remove that key.
      title: Metadata
    type_inboxes:Inbox:
      type: object
      properties:
        pod_id:
          $ref: '#/components/schemas/type_pods:PodId'
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        email:
          $ref: '#/components/schemas/type_inboxes:Email'
        display_name:
          $ref: '#/components/schemas/type_inboxes:DisplayName'
        client_id:
          $ref: '#/components/schemas/type_inboxes:ClientId'
        metadata:
          $ref: '#/components/schemas/type_inboxes:Metadata'
          description: Custom metadata attached to the inbox.
        updated_at:
          type: string
          format: date-time
          description: Time at which inbox was last updated.
        created_at:
          type: string
          format: date-time
          description: Time at which inbox was created.
      required:
        - pod_id
        - inbox_id
        - email
        - updated_at
        - created_at
      title: Inbox
    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
    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: bearer

Examples

Request

json

{}

Response

json

{
  "pod_id": "pod_id",
  "inbox_id": "inbox_id",
  "email": "email",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "display_name": "display_name",
  "client_id": "client_id",
  "metadata": {
    "metadata": "metadata"
  }
}

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.update("inbox_id", {});
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.update(
    inbox_id="inbox_id",
)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", 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/inboxes/inbox_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.agentmail.to/v0/inboxes/inbox_id")
  .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('PATCH', 'https://api.agentmail.to/v0/inboxes/inbox_id', [
  '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/inboxes/inbox_id");
var request = new RestRequest(Method.PATCH);
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/inboxes/inbox_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
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()

Delete Inbox

DELETE https://api.agentmail.to/v0/inboxes/{inbox_id}

CLI:

bash

agentmail inboxes delete --inbox-id <inbox_id>

OpenAPI Specification

yaml

openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}:
    delete:
      operationId: delete
      summary: Delete Inbox
      description: |-
        **CLI:**
        ```bash
        agentmail inboxes delete --inbox-id <inbox_id>
        ```
      tags:
        - subpackage_inboxes
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - 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_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    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: bearer

Examples

SDK Code

typescript

import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.delete("inbox_id");
}
main();

python

from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.delete(
    inbox_id="inbox_id",
)

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_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/inboxes/inbox_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_body

java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.delete("https://api.agentmail.to/v0/inboxes/inbox_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/inboxes/inbox_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();

csharp

using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_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/inboxes/inbox_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()

Inboxes ​

Inboxes Overview ​

OpenAPI Specification ​

Examples ​

Create Inbox ​

OpenAPI Specification ​

Examples ​

Get Inbox ​

OpenAPI Specification ​

Examples ​

List Inboxes ​

OpenAPI Specification ​

Examples ​

Update Inbox ​

OpenAPI Specification ​

Examples ​

Delete Inbox ​

OpenAPI Specification ​

Examples ​

Inboxes

Inboxes Overview

OpenAPI Specification

Examples

Create Inbox

OpenAPI Specification

Examples

Get Inbox

OpenAPI Specification

Examples

List Inboxes

OpenAPI Specification

Examples

Update Inbox

OpenAPI Specification

Examples

Delete Inbox

OpenAPI Specification

Examples