AgentMail Docs

Appearance

Threads ​

Fresh 🌱

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

Threads Overview ​

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

Lists threads, most recent first. Pass senders, recipients, or subject to filter by substring. Filtered requests are served by search, which caps limit at 100. For relevance-ranked full-text search across senders, recipients, subject, and message body, use Search Threads.

CLI:

bash
agentmail threads list

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/threads:
    get:
      operationId: list
      summary: List Threads
      description: |-
        Lists threads, most recent first. Pass `senders`, `recipients`, or
        `subject` to filter by substring. Filtered requests are served by
        search, which caps `limit` at 100. For relevance-ranked full-text
        search across senders, recipients, subject, and message body, use
        `Search Threads`.

        **CLI:**
        ```bash
        agentmail threads list
        ```
      tags:
        - subpackage_threads
      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: labels
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Labels'
        - name: before
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Before'
        - name: after
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:After'
        - name: ascending
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Ascending'
        - name: include_spam
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeSpam'
        - name: include_blocked
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeBlocked'
        - name: include_unauthenticated
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeUnauthenticated'
        - name: include_trash
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeTrash'
        - name: senders
          in: query
          description: >-
            Filter to threads whose senders contain this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: recipients
          in: query
          description: >-
            Filter to threads whose recipients contain this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: subject
          in: query
          description: >-
            Filter to threads whose subject contains this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - 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_threads:ListThreadsResponse'
        '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_:Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_:PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    type_:Labels:
      type: array
      items:
        type: string
      description: Labels to filter by.
      title: Labels
    type_:Before:
      type: string
      format: date-time
      description: Timestamp before which to filter by.
      title: Before
    type_:After:
      type: string
      format: date-time
      description: Timestamp after which to filter by.
      title: After
    type_:Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type_:IncludeSpam:
      type: boolean
      description: Include spam in results.
      title: IncludeSpam
    type_:IncludeBlocked:
      type: boolean
      description: Include blocked in results.
      title: IncludeBlocked
    type_:IncludeUnauthenticated:
      type: boolean
      description: Include unauthenticated in results.
      title: IncludeUnauthenticated
    type_:IncludeTrash:
      type: boolean
      description: Include trash in results.
      title: IncludeTrash
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_inboxes:InboxId:
      type: string
      description: The ID of the inbox.
      title: InboxId
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:ThreadTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent or received message.
      title: ThreadTimestamp
    type_threads:ThreadReceivedTimestamp:
      type: string
      format: date-time
      description: Timestamp of last received message.
      title: ThreadReceivedTimestamp
    type_threads:ThreadSentTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent message.
      title: ThreadSentTimestamp
    type_threads:ThreadSenders:
      type: array
      items:
        type: string
      description: >-
        Senders in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadSenders
    type_threads:ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadRecipients
    type_threads:ThreadSubject:
      type: string
      description: Subject of thread.
      title: ThreadSubject
    type_threads:ThreadPreview:
      type: string
      description: Text preview of last message in thread.
      title: ThreadPreview
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:Attachment:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
      required:
        - attachment_id
        - size
      title: Attachment
    type_threads:ThreadAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in thread.
      title: ThreadAttachments
    type_threads:ThreadLastMessageId:
      type: string
      description: ID of last message in thread.
      title: ThreadLastMessageId
    type_threads:ThreadMessageCount:
      type: integer
      description: Number of messages in thread.
      title: ThreadMessageCount
    type_threads:ThreadSize:
      type: integer
      description: Size of thread in bytes.
      title: ThreadSize
    type_threads:ThreadUpdatedAt:
      type: string
      format: date-time
      description: Time at which thread was last updated.
      title: ThreadUpdatedAt
    type_threads:ThreadCreatedAt:
      type: string
      format: date-time
      description: Time at which thread was created.
      title: ThreadCreatedAt
    type_threads:ThreadItem:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
        timestamp:
          $ref: '#/components/schemas/type_threads:ThreadTimestamp'
        received_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadReceivedTimestamp'
        sent_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadSentTimestamp'
        senders:
          $ref: '#/components/schemas/type_threads:ThreadSenders'
        recipients:
          $ref: '#/components/schemas/type_threads:ThreadRecipients'
        subject:
          $ref: '#/components/schemas/type_threads:ThreadSubject'
        preview:
          $ref: '#/components/schemas/type_threads:ThreadPreview'
        attachments:
          $ref: '#/components/schemas/type_threads:ThreadAttachments'
        last_message_id:
          $ref: '#/components/schemas/type_threads:ThreadLastMessageId'
        message_count:
          $ref: '#/components/schemas/type_threads:ThreadMessageCount'
        size:
          $ref: '#/components/schemas/type_threads:ThreadSize'
        updated_at:
          $ref: '#/components/schemas/type_threads:ThreadUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_threads:ThreadCreatedAt'
      required:
        - inbox_id
        - thread_id
        - labels
        - timestamp
        - senders
        - recipients
        - last_message_id
        - message_count
        - size
        - updated_at
        - created_at
      title: ThreadItem
    type_threads:ListThreadsResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        threads:
          type: array
          items:
            $ref: '#/components/schemas/type_threads:ThreadItem'
          description: Ordered by `timestamp` descending.
      required:
        - count
        - threads
      title: ListThreadsResponse
    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
{
  "count": 1,
  "threads": [
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "senders": [
        "senders",
        "senders"
      ],
      "recipients": [
        "recipients",
        "recipients"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject",
      "preview": "preview",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ]
    },
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "senders": [
        "senders",
        "senders"
      ],
      "recipients": [
        "recipients",
        "recipients"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject",
      "preview": "preview",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ]
    }
  ],
  "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.threads.list({});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.threads.list()
go
package main

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

func main() {

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

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

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/threads")
  .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/threads', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

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

Get Thread ​

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

CLI:

bash
agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id <thread_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads/{thread_id}:
    get:
      operationId: get
      summary: Get Thread
      description: >-
        **CLI:**

        ```bash

        agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id
        <thread_id>

        ```
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - name: thread_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_threads:ThreadId'
        - 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_threads:Thread'
        '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_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:ThreadTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent or received message.
      title: ThreadTimestamp
    type_threads:ThreadReceivedTimestamp:
      type: string
      format: date-time
      description: Timestamp of last received message.
      title: ThreadReceivedTimestamp
    type_threads:ThreadSentTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent message.
      title: ThreadSentTimestamp
    type_threads:ThreadSenders:
      type: array
      items:
        type: string
      description: >-
        Senders in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadSenders
    type_threads:ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadRecipients
    type_threads:ThreadSubject:
      type: string
      description: Subject of thread.
      title: ThreadSubject
    type_threads:ThreadPreview:
      type: string
      description: Text preview of last message in thread.
      title: ThreadPreview
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:Attachment:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
      required:
        - attachment_id
        - size
      title: Attachment
    type_threads:ThreadAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in thread.
      title: ThreadAttachments
    type_threads:ThreadLastMessageId:
      type: string
      description: ID of last message in thread.
      title: ThreadLastMessageId
    type_threads:ThreadMessageCount:
      type: integer
      description: Number of messages in thread.
      title: ThreadMessageCount
    type_threads:ThreadSize:
      type: integer
      description: Size of thread in bytes.
      title: ThreadSize
    type_threads:ThreadUpdatedAt:
      type: string
      format: date-time
      description: Time at which thread was last updated.
      title: ThreadUpdatedAt
    type_threads:ThreadCreatedAt:
      type: string
      format: date-time
      description: Time at which thread was created.
      title: ThreadCreatedAt
    type_messages:MessageId:
      type: string
      description: ID of message.
      title: MessageId
    type_messages:MessageLabels:
      type: array
      items:
        type: string
      description: Labels of message.
      title: MessageLabels
    type_messages:MessageTimestamp:
      type: string
      format: date-time
      description: Time at which message was sent or drafted.
      title: MessageTimestamp
    type_messages:MessageFrom:
      type: string
      description: >-
        Address of sender. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: MessageFrom
    type_messages:MessageTo:
      type: array
      items:
        type: string
      description: >-
        Addresses of recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageTo
    type_messages:MessageCc:
      type: array
      items:
        type: string
      description: >-
        Addresses of CC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageCc
    type_messages:MessageBcc:
      type: array
      items:
        type: string
      description: >-
        Addresses of BCC recipients. In format `username@domain.com` or `Display
        Name <username@domain.com>`.
      title: MessageBcc
    type_messages:MessageSubject:
      type: string
      description: Subject of message.
      title: MessageSubject
    type_messages:MessagePreview:
      type: string
      description: Text preview of message.
      title: MessagePreview
    type_messages:MessageText:
      type: string
      description: Plain text body of message.
      title: MessageText
    type_messages:MessageHtml:
      type: string
      description: HTML body of message.
      title: MessageHtml
    type_messages:MessageAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in message.
      title: MessageAttachments
    type_messages:MessageInReplyTo:
      type: string
      description: ID of message being replied to.
      title: MessageInReplyTo
    type_messages:MessageReferences:
      type: array
      items:
        type: string
      description: IDs of previous messages in thread.
      title: MessageReferences
    type_messages:MessageHeaders:
      type: object
      additionalProperties:
        type: string
      description: Headers in message.
      title: MessageHeaders
    type_messages:MessageSize:
      type: integer
      description: Size of message in bytes.
      title: MessageSize
    type_messages:MessageUpdatedAt:
      type: string
      format: date-time
      description: Time at which message was last updated.
      title: MessageUpdatedAt
    type_messages:MessageCreatedAt:
      type: string
      format: date-time
      description: Time at which message was created.
      title: MessageCreatedAt
    type_messages:Message:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        message_id:
          $ref: '#/components/schemas/type_messages:MessageId'
        labels:
          $ref: '#/components/schemas/type_messages:MessageLabels'
        timestamp:
          $ref: '#/components/schemas/type_messages:MessageTimestamp'
        from:
          $ref: '#/components/schemas/type_messages:MessageFrom'
        reply_to:
          type: array
          items:
            type: string
          description: >-
            Reply-to addresses. In format `username@domain.com` or `Display Name
            <username@domain.com>`.
        to:
          $ref: '#/components/schemas/type_messages:MessageTo'
        cc:
          $ref: '#/components/schemas/type_messages:MessageCc'
        bcc:
          $ref: '#/components/schemas/type_messages:MessageBcc'
        subject:
          $ref: '#/components/schemas/type_messages:MessageSubject'
        preview:
          $ref: '#/components/schemas/type_messages:MessagePreview'
        text:
          $ref: '#/components/schemas/type_messages:MessageText'
        html:
          $ref: '#/components/schemas/type_messages:MessageHtml'
        extracted_text:
          type: string
          description: Extracted new text content.
        extracted_html:
          type: string
          description: Extracted new HTML content.
        attachments:
          $ref: '#/components/schemas/type_messages:MessageAttachments'
        in_reply_to:
          $ref: '#/components/schemas/type_messages:MessageInReplyTo'
        references:
          $ref: '#/components/schemas/type_messages:MessageReferences'
        headers:
          $ref: '#/components/schemas/type_messages:MessageHeaders'
        size:
          $ref: '#/components/schemas/type_messages:MessageSize'
        updated_at:
          $ref: '#/components/schemas/type_messages:MessageUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_messages:MessageCreatedAt'
      required:
        - inbox_id
        - thread_id
        - message_id
        - labels
        - timestamp
        - from
        - to
        - size
        - updated_at
        - created_at
      title: Message
    type_threads:Thread:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
        timestamp:
          $ref: '#/components/schemas/type_threads:ThreadTimestamp'
        received_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadReceivedTimestamp'
        sent_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadSentTimestamp'
        senders:
          $ref: '#/components/schemas/type_threads:ThreadSenders'
        recipients:
          $ref: '#/components/schemas/type_threads:ThreadRecipients'
        subject:
          $ref: '#/components/schemas/type_threads:ThreadSubject'
        preview:
          $ref: '#/components/schemas/type_threads:ThreadPreview'
        attachments:
          $ref: '#/components/schemas/type_threads:ThreadAttachments'
        last_message_id:
          $ref: '#/components/schemas/type_threads:ThreadLastMessageId'
        message_count:
          $ref: '#/components/schemas/type_threads:ThreadMessageCount'
        size:
          $ref: '#/components/schemas/type_threads:ThreadSize'
        updated_at:
          $ref: '#/components/schemas/type_threads:ThreadUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_threads:ThreadCreatedAt'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_messages:Message'
          description: Messages in thread. Ordered by `timestamp` ascending.
      required:
        - inbox_id
        - thread_id
        - labels
        - timestamp
        - senders
        - recipients
        - last_message_id
        - message_count
        - size
        - updated_at
        - created_at
        - messages
      title: Thread
    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
{
  "inbox_id": "inbox_id",
  "thread_id": "thread_id",
  "labels": [
    "labels",
    "labels"
  ],
  "timestamp": "2024-01-15T09:30:00Z",
  "senders": [
    "senders",
    "senders"
  ],
  "recipients": [
    "recipients",
    "recipients"
  ],
  "last_message_id": "last_message_id",
  "message_count": 1,
  "size": 1,
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "messages": [
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "message_id": "message_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "from": "from",
      "to": [
        "to",
        "to"
      ],
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "reply_to": [
        "reply_to",
        "reply_to"
      ],
      "cc": [
        "cc",
        "cc"
      ],
      "bcc": [
        "bcc",
        "bcc"
      ],
      "subject": "subject",
      "preview": "preview",
      "text": "text",
      "html": "html",
      "extracted_text": "extracted_text",
      "extracted_html": "extracted_html",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ],
      "in_reply_to": "in_reply_to",
      "references": [
        "references",
        "references"
      ],
      "headers": {
        "headers": "headers"
      }
    },
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "message_id": "message_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "from": "from",
      "to": [
        "to",
        "to"
      ],
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "reply_to": [
        "reply_to",
        "reply_to"
      ],
      "cc": [
        "cc",
        "cc"
      ],
      "bcc": [
        "bcc",
        "bcc"
      ],
      "subject": "subject",
      "preview": "preview",
      "text": "text",
      "html": "html",
      "extracted_text": "extracted_text",
      "extracted_html": "extracted_html",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ],
      "in_reply_to": "in_reply_to",
      "references": [
        "references",
        "references"
      ],
      "headers": {
        "headers": "headers"
      }
    }
  ],
  "received_timestamp": "2024-01-15T09:30:00Z",
  "sent_timestamp": "2024-01-15T09:30:00Z",
  "subject": "subject",
  "preview": "preview",
  "attachments": [
    {
      "attachment_id": "attachment_id",
      "size": 1,
      "filename": "filename",
      "content_type": "content_type",
      "content_disposition": "inline",
      "content_id": "content_id"
    },
    {
      "attachment_id": "attachment_id",
      "size": 1,
      "filename": "filename",
      "content_type": "content_type",
      "content_disposition": "inline",
      "content_id": "content_id"
    }
  ]
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.threads.get("inbox_id", "thread_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.get(
    inbox_id="inbox_id",
    thread_id="thread_id",
)
go
package main

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

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/threads/thread_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/threads/thread_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/threads/thread_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/threads/thread_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_id/threads/thread_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/threads/thread_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 Threads ​

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

Lists threads in the inbox, most recent first. Pass senders, recipients, or subject to filter by substring. Filtered requests are served by search, which caps limit at 100. For relevance-ranked full-text search, use Search Threads.

CLI:

bash
agentmail inboxes:threads list --inbox-id <inbox_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads:
    get:
      operationId: list
      summary: List Threads
      description: |-
        Lists threads in the inbox, most recent first. Pass `senders`,
        `recipients`, or `subject` to filter by substring. Filtered requests are
        served by search, which caps `limit` at 100. For relevance-ranked
        full-text search, use `Search Threads`.

        **CLI:**
        ```bash
        agentmail inboxes:threads list --inbox-id <inbox_id>
        ```
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - 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: labels
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Labels'
        - name: before
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Before'
        - name: after
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:After'
        - name: ascending
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Ascending'
        - name: include_spam
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeSpam'
        - name: include_blocked
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeBlocked'
        - name: include_unauthenticated
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeUnauthenticated'
        - name: include_trash
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:IncludeTrash'
        - name: senders
          in: query
          description: >-
            Filter to threads whose senders contain this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: recipients
          in: query
          description: >-
            Filter to threads whose recipients contain this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: subject
          in: query
          description: >-
            Filter to threads whose subject contains this value (substring
            match). Repeatable; all values must match.
          required: false
          schema:
            type: array
            items:
              type: string
        - 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_threads:ListThreadsResponse'
        '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_:Limit:
      type: integer
      description: Limit of number of items returned.
      title: Limit
    type_:PageToken:
      type: string
      description: Page token for pagination.
      title: PageToken
    type_:Labels:
      type: array
      items:
        type: string
      description: Labels to filter by.
      title: Labels
    type_:Before:
      type: string
      format: date-time
      description: Timestamp before which to filter by.
      title: Before
    type_:After:
      type: string
      format: date-time
      description: Timestamp after which to filter by.
      title: After
    type_:Ascending:
      type: boolean
      description: Sort in ascending temporal order.
      title: Ascending
    type_:IncludeSpam:
      type: boolean
      description: Include spam in results.
      title: IncludeSpam
    type_:IncludeBlocked:
      type: boolean
      description: Include blocked in results.
      title: IncludeBlocked
    type_:IncludeUnauthenticated:
      type: boolean
      description: Include unauthenticated in results.
      title: IncludeUnauthenticated
    type_:IncludeTrash:
      type: boolean
      description: Include trash in results.
      title: IncludeTrash
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:ThreadTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent or received message.
      title: ThreadTimestamp
    type_threads:ThreadReceivedTimestamp:
      type: string
      format: date-time
      description: Timestamp of last received message.
      title: ThreadReceivedTimestamp
    type_threads:ThreadSentTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent message.
      title: ThreadSentTimestamp
    type_threads:ThreadSenders:
      type: array
      items:
        type: string
      description: >-
        Senders in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadSenders
    type_threads:ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadRecipients
    type_threads:ThreadSubject:
      type: string
      description: Subject of thread.
      title: ThreadSubject
    type_threads:ThreadPreview:
      type: string
      description: Text preview of last message in thread.
      title: ThreadPreview
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:Attachment:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
      required:
        - attachment_id
        - size
      title: Attachment
    type_threads:ThreadAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in thread.
      title: ThreadAttachments
    type_threads:ThreadLastMessageId:
      type: string
      description: ID of last message in thread.
      title: ThreadLastMessageId
    type_threads:ThreadMessageCount:
      type: integer
      description: Number of messages in thread.
      title: ThreadMessageCount
    type_threads:ThreadSize:
      type: integer
      description: Size of thread in bytes.
      title: ThreadSize
    type_threads:ThreadUpdatedAt:
      type: string
      format: date-time
      description: Time at which thread was last updated.
      title: ThreadUpdatedAt
    type_threads:ThreadCreatedAt:
      type: string
      format: date-time
      description: Time at which thread was created.
      title: ThreadCreatedAt
    type_threads:ThreadItem:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
        timestamp:
          $ref: '#/components/schemas/type_threads:ThreadTimestamp'
        received_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadReceivedTimestamp'
        sent_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadSentTimestamp'
        senders:
          $ref: '#/components/schemas/type_threads:ThreadSenders'
        recipients:
          $ref: '#/components/schemas/type_threads:ThreadRecipients'
        subject:
          $ref: '#/components/schemas/type_threads:ThreadSubject'
        preview:
          $ref: '#/components/schemas/type_threads:ThreadPreview'
        attachments:
          $ref: '#/components/schemas/type_threads:ThreadAttachments'
        last_message_id:
          $ref: '#/components/schemas/type_threads:ThreadLastMessageId'
        message_count:
          $ref: '#/components/schemas/type_threads:ThreadMessageCount'
        size:
          $ref: '#/components/schemas/type_threads:ThreadSize'
        updated_at:
          $ref: '#/components/schemas/type_threads:ThreadUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_threads:ThreadCreatedAt'
      required:
        - inbox_id
        - thread_id
        - labels
        - timestamp
        - senders
        - recipients
        - last_message_id
        - message_count
        - size
        - updated_at
        - created_at
      title: ThreadItem
    type_threads:ListThreadsResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        threads:
          type: array
          items:
            $ref: '#/components/schemas/type_threads:ThreadItem'
          description: Ordered by `timestamp` descending.
      required:
        - count
        - threads
      title: ListThreadsResponse
    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
{
  "count": 1,
  "threads": [
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "senders": [
        "senders",
        "senders"
      ],
      "recipients": [
        "recipients",
        "recipients"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject",
      "preview": "preview",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ]
    },
    {
      "inbox_id": "inbox_id",
      "thread_id": "thread_id",
      "labels": [
        "labels",
        "labels"
      ],
      "timestamp": "2024-01-15T09:30:00Z",
      "senders": [
        "senders",
        "senders"
      ],
      "recipients": [
        "recipients",
        "recipients"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "size": 1,
      "updated_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject",
      "preview": "preview",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ]
    }
  ],
  "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.threads.list("inbox_id", {});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.list(
    inbox_id="inbox_id",
)
go
package main

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

func main() {

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

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

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/threads")
  .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/threads', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

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

Search Threads ​

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

Full-text search across threads in the inbox, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated threads are always excluded. limit cannot exceed 100.

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads/search:
    get:
      operationId: search
      summary: Search Threads
      description: |-
        Full-text search across threads in the inbox, ranked by relevance. The
        query is matched against senders, recipients, and subject (substring)
        and the message body (tokenized full text). Spam, trash, blocked, and
        unauthenticated threads are always excluded. `limit` cannot exceed 100.
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - name: q
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/type_:Query'
        - 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: before
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:Before'
        - name: after
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_:After'
        - 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_threads:SearchThreadsResponse'
        '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'
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_:Query:
      type: string
      description: |-
        Full-text search query. Matched against the sender, recipients, and
        subject (substring) and the message body (tokenized full text).
      title: Query
    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_:Before:
      type: string
      format: date-time
      description: Timestamp before which to filter by.
      title: Before
    type_:After:
      type: string
      format: date-time
      description: Timestamp after which to filter by.
      title: After
    type_:Count:
      type: integer
      description: Number of items returned.
      title: Count
    type_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:ThreadTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent or received message.
      title: ThreadTimestamp
    type_threads:ThreadReceivedTimestamp:
      type: string
      format: date-time
      description: Timestamp of last received message.
      title: ThreadReceivedTimestamp
    type_threads:ThreadSentTimestamp:
      type: string
      format: date-time
      description: Timestamp of last sent message.
      title: ThreadSentTimestamp
    type_threads:ThreadSenders:
      type: array
      items:
        type: string
      description: >-
        Senders in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadSenders
    type_threads:ThreadRecipients:
      type: array
      items:
        type: string
      description: >-
        Recipients in thread. In format `username@domain.com` or `Display Name
        <username@domain.com>`.
      title: ThreadRecipients
    type_threads:ThreadSubject:
      type: string
      description: Subject of thread.
      title: ThreadSubject
    type_threads:ThreadPreview:
      type: string
      description: Text preview of last message in thread.
      title: ThreadPreview
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:Attachment:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
      required:
        - attachment_id
        - size
      title: Attachment
    type_threads:ThreadAttachments:
      type: array
      items:
        $ref: '#/components/schemas/type_attachments:Attachment'
      description: Attachments in thread.
      title: ThreadAttachments
    type_threads:ThreadLastMessageId:
      type: string
      description: ID of last message in thread.
      title: ThreadLastMessageId
    type_threads:ThreadMessageCount:
      type: integer
      description: Number of messages in thread.
      title: ThreadMessageCount
    type_threads:ThreadSize:
      type: integer
      description: Size of thread in bytes.
      title: ThreadSize
    type_threads:ThreadUpdatedAt:
      type: string
      format: date-time
      description: Time at which thread was last updated.
      title: ThreadUpdatedAt
    type_threads:ThreadCreatedAt:
      type: string
      format: date-time
      description: Time at which thread was created.
      title: ThreadCreatedAt
    type_threads:SearchThreadHighlights:
      type: object
      properties:
        from:
          type: array
          items:
            type: string
          description: Matched fragments from a sender address in the thread.
        recipients:
          type: array
          items:
            type: string
          description: >-
            Matched fragments from a recipient address in the thread (to, cc, or
            bcc).
        subject:
          type: array
          items:
            type: string
          description: Matched fragments from the subject.
        text:
          type: array
          items:
            type: string
          description: Matched fragments from a message body in the thread.
      description: >-
        Matched fragments per field on a thread search result, with matched
        terms

        wrapped in `**`. A field key is present only when the query matched that

        field, so the present keys also tell you which fields produced the hit.
      title: SearchThreadHighlights
    type_threads:SearchThreadItem:
      type: object
      properties:
        inbox_id:
          $ref: '#/components/schemas/type_inboxes:InboxId'
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
        timestamp:
          $ref: '#/components/schemas/type_threads:ThreadTimestamp'
        received_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadReceivedTimestamp'
        sent_timestamp:
          $ref: '#/components/schemas/type_threads:ThreadSentTimestamp'
        senders:
          $ref: '#/components/schemas/type_threads:ThreadSenders'
        recipients:
          $ref: '#/components/schemas/type_threads:ThreadRecipients'
        subject:
          $ref: '#/components/schemas/type_threads:ThreadSubject'
        preview:
          $ref: '#/components/schemas/type_threads:ThreadPreview'
        attachments:
          $ref: '#/components/schemas/type_threads:ThreadAttachments'
        last_message_id:
          $ref: '#/components/schemas/type_threads:ThreadLastMessageId'
        message_count:
          $ref: '#/components/schemas/type_threads:ThreadMessageCount'
        size:
          $ref: '#/components/schemas/type_threads:ThreadSize'
        updated_at:
          $ref: '#/components/schemas/type_threads:ThreadUpdatedAt'
        created_at:
          $ref: '#/components/schemas/type_threads:ThreadCreatedAt'
        highlights:
          $ref: '#/components/schemas/type_threads:SearchThreadHighlights'
          description: >-
            Matched fragments per field. Present only when the query matched an
            indexed field.
      required:
        - inbox_id
        - thread_id
        - labels
        - timestamp
        - senders
        - recipients
        - last_message_id
        - message_count
        - size
        - updated_at
        - created_at
      title: SearchThreadItem
    type_threads:SearchThreadsResponse:
      type: object
      properties:
        count:
          $ref: '#/components/schemas/type_:Count'
        limit:
          $ref: '#/components/schemas/type_:Limit'
        next_page_token:
          $ref: '#/components/schemas/type_:PageToken'
        threads:
          type: array
          items:
            $ref: '#/components/schemas/type_threads:SearchThreadItem'
          description: Ordered by relevance, best match first.
      required:
        - count
        - threads
      title: SearchThreadsResponse
    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 ​

Response

json
{
  "count": 1,
  "threads": [
    {
      "created_at": "2024-01-15T09:30:00Z",
      "inbox_id": "inbox_id",
      "labels": [
        "labels",
        "labels"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "recipients": [
        "recipients",
        "recipients"
      ],
      "senders": [
        "senders",
        "senders"
      ],
      "size": 1,
      "thread_id": "thread_id",
      "timestamp": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ],
      "highlights": {
        "from": [
          "from",
          "from"
        ],
        "recipients": [
          "recipients",
          "recipients"
        ],
        "subject": [
          "subject",
          "subject"
        ],
        "text": [
          "text",
          "text"
        ]
      },
      "preview": "preview",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject"
    },
    {
      "created_at": "2024-01-15T09:30:00Z",
      "inbox_id": "inbox_id",
      "labels": [
        "labels",
        "labels"
      ],
      "last_message_id": "last_message_id",
      "message_count": 1,
      "recipients": [
        "recipients",
        "recipients"
      ],
      "senders": [
        "senders",
        "senders"
      ],
      "size": 1,
      "thread_id": "thread_id",
      "timestamp": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "attachments": [
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        },
        {
          "attachment_id": "attachment_id",
          "size": 1,
          "filename": "filename",
          "content_type": "content_type",
          "content_disposition": "inline",
          "content_id": "content_id"
        }
      ],
      "highlights": {
        "from": [
          "from",
          "from"
        ],
        "recipients": [
          "recipients",
          "recipients"
        ],
        "subject": [
          "subject",
          "subject"
        ],
        "text": [
          "text",
          "text"
        ]
      },
      "preview": "preview",
      "received_timestamp": "2024-01-15T09:30:00Z",
      "sent_timestamp": "2024-01-15T09:30:00Z",
      "subject": "subject"
    }
  ],
  "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.threads.search("inbox_id", {
        q: "q",
    });
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.search(
    inbox_id="inbox_id",
    q="q",
)
go
package main

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

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/threads/search?q=q"

	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/threads/search?q=q")

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/threads/search?q=q")
  .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/threads/search?q=q', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

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

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

Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a 422 for threads with 100 or more messages.

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads/{thread_id}:
    patch:
      operationId: update
      summary: Update Thread
      description: >-
        Updates thread labels. Cannot add or remove system labels (sent,
        received, bounced, etc.). Rejects requests with a `422` for threads with
        100 or more messages.
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - name: thread_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_threads:ThreadId'
        - 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_threads:UpdateThreadResponse'
        '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'
        '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_threads:UpdateThreadRequest'
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_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_threads:UpdateThreadRequest:
      type: object
      properties:
        add_labels:
          type: array
          items:
            type: string
          description: Labels to add to thread. Cannot be system labels.
        remove_labels:
          type: array
          items:
            type: string
          description: >-
            Labels to remove from thread. Cannot be system labels. Takes
            priority over `add_labels` (in the event of duplicate labels passed
            in).
      title: UpdateThreadRequest
    type_threads:ThreadLabels:
      type: array
      items:
        type: string
      description: Labels of thread.
      title: ThreadLabels
    type_threads:UpdateThreadResponse:
      type: object
      properties:
        thread_id:
          $ref: '#/components/schemas/type_threads:ThreadId'
        labels:
          $ref: '#/components/schemas/type_threads:ThreadLabels'
      required:
        - thread_id
        - labels
      title: UpdateThreadResponse
    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
{}

Response

json
{
  "thread_id": "thread_id",
  "labels": [
    "labels",
    "labels"
  ]
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.threads.update("inbox_id", "thread_id", {});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.update(
    inbox_id="inbox_id",
    thread_id="thread_id",
)
go
package main

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

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/threads/thread_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/threads/thread_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/threads/thread_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/threads/thread_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/threads/thread_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/threads/thread_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 Thread ​

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

Moves the thread to trash by adding a trash label to all messages. If the thread is already in trash, it will be permanently deleted. Use permanent=true to force permanent deletion.

CLI:

bash
agentmail inboxes:threads delete --inbox-id <inbox_id> --thread-id <thread_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads/{thread_id}:
    delete:
      operationId: delete
      summary: Delete Thread
      description: >-
        Moves the thread to trash by adding a trash label to all messages. If
        the thread is already in trash, it will be permanently deleted. Use
        `permanent=true` to force permanent deletion.

        **CLI:**

        ```bash

        agentmail inboxes:threads delete --inbox-id <inbox_id> --thread-id
        <thread_id>

        ```
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - name: thread_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_threads:ThreadId'
        - name: permanent
          in: query
          description: If true, permanently delete the thread instead of moving to trash.
          required: false
          schema:
            type: boolean
        - 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_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    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.threads.delete("inbox_id", "thread_id", {});
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.delete(
    inbox_id="inbox_id",
    thread_id="thread_id",
)
go
package main

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

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/threads/thread_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/threads/thread_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/threads/thread_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/threads/thread_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

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

Get Thread Attachment ​

GET https://api.agentmail.to/v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}

CLI:

bash
agentmail inboxes:threads get-attachment --inbox-id <inbox_id> --thread-id <thread_id> --attachment-id <attachment_id>

OpenAPI Specification ​

yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
paths:
  /v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}:
    get:
      operationId: get-attachment
      summary: Get Attachment
      description: >-
        **CLI:**

        ```bash

        agentmail inboxes:threads get-attachment --inbox-id <inbox_id>
        --thread-id <thread_id> --attachment-id <attachment_id>

        ```
      tags:
        - subpackage_inboxes.subpackage_inboxes/threads
      parameters:
        - name: inbox_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_inboxes:InboxId'
        - name: thread_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_threads:ThreadId'
        - name: attachment_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_attachments:AttachmentId'
        - 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_attachments:AttachmentResponse'
        '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_threads:ThreadId:
      type: string
      description: ID of thread.
      title: ThreadId
    type_attachments:AttachmentId:
      type: string
      description: ID of attachment.
      title: AttachmentId
    type_attachments:AttachmentFilename:
      type: string
      description: Filename of attachment.
      title: AttachmentFilename
    type_attachments:AttachmentSize:
      type: integer
      description: Size of attachment in bytes.
      title: AttachmentSize
    type_attachments:AttachmentContentType:
      type: string
      description: Content type of attachment.
      title: AttachmentContentType
    type_attachments:AttachmentContentDisposition:
      type: string
      enum:
        - inline
        - attachment
      description: Content disposition of attachment.
      title: AttachmentContentDisposition
    type_attachments:AttachmentContentId:
      type: string
      description: Content ID of attachment.
      title: AttachmentContentId
    type_attachments:AttachmentResponse:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/type_attachments:AttachmentId'
        filename:
          $ref: '#/components/schemas/type_attachments:AttachmentFilename'
        size:
          $ref: '#/components/schemas/type_attachments:AttachmentSize'
        content_type:
          $ref: '#/components/schemas/type_attachments:AttachmentContentType'
        content_disposition:
          $ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
        content_id:
          $ref: '#/components/schemas/type_attachments:AttachmentContentId'
        download_url:
          type: string
          description: URL to download the attachment.
        expires_at:
          type: string
          format: date-time
          description: Time at which the download URL expires.
      required:
        - attachment_id
        - size
        - download_url
        - expires_at
      title: AttachmentResponse
    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
{
  "attachment_id": "attachment_id",
  "size": 1,
  "download_url": "download_url",
  "expires_at": "2024-01-15T09:30:00Z",
  "filename": "filename",
  "content_type": "content_type",
  "content_disposition": "inline",
  "content_id": "content_id"
}

SDK Code

typescript
import { AgentMailClient } from "agentmail";

async function main() {
    const client = new AgentMailClient({
        apiKey: "YOUR_TOKEN_HERE",
    });
    await client.inboxes.threads.getAttachment("inbox_id", "thread_id", "attachment_id");
}
main();
python
from agentmail import AgentMail

client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)

client.inboxes.threads.get_attachment(
    inbox_id="inbox_id",
    thread_id="thread_id",
    attachment_id="attachment_id",
)
go
package main

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

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/threads/thread_id/attachments/attachment_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/threads/thread_id/attachments/attachment_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/threads/thread_id/attachments/attachment_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/threads/thread_id/attachments/attachment_id', [
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
  ],
]);

echo $response->getBody();
csharp
using RestSharp;

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