AgentMail inboxes > drafts API
The inboxes > drafts API from AgentMail — 4 operation(s) for inboxes > drafts.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference agent inboxes > drafts API
version: 1.0.0
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
tags:
- name: inboxes > drafts
paths:
/v0/inboxes/{inbox_id}/drafts:
get:
operationId: list
summary: List Drafts
description: '**CLI:**
```bash
agentmail inboxes:drafts list --inbox-id <inbox_id>
```'
tags:
- inboxes > drafts
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: 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_drafts:ListDraftsResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
post:
operationId: create
summary: Create Draft
description: 'Create a draft. Supply `in_reply_to` to create a reply draft (with
`reply_all` to address the whole thread), whose recipients, subject, and
threading are derived from the referenced message, or `forward_of` to
create a forward draft, which derives the subject, threading, and
forwarded content from the source but keeps recipients caller-supplied.
**CLI:**
```bash
agentmail inboxes:drafts create --inbox-id <inbox_id> --to recipient@example.com --subject "Draft subject" --text "Draft body"
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/type_drafts:Draft'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_drafts:CreateDraftRequest'
/v0/inboxes/{inbox_id}/drafts/{draft_id}:
get:
operationId: get
summary: Get Draft
description: '**CLI:**
```bash
agentmail inboxes:drafts get --inbox-id <inbox_id> --draft-id <draft_id>
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_drafts:DraftId'
- 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_drafts:Draft'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
patch:
operationId: update
summary: Update Draft
description: 'Edit fields on an existing draft. Passing `null` clears a field (or `[]`
for a recipient field); `send_at: null` un-schedules a scheduled draft.
A draft that is already being sent cannot be edited.
**CLI:**
```bash
agentmail inboxes:drafts update --inbox-id <inbox_id> --draft-id <draft_id> --subject "Updated subject"
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_drafts:DraftId'
- 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_drafts:Draft'
'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'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_drafts:UpdateDraftRequest'
delete:
operationId: delete
summary: Delete Draft
description: '**CLI:**
```bash
agentmail inboxes:drafts delete --inbox-id <inbox_id> --draft-id <draft_id>
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_drafts:DraftId'
- 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'
/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}:
get:
operationId: get-attachment
summary: Get Attachment
description: '**CLI:**
```bash
agentmail inboxes:drafts get-attachment --inbox-id <inbox_id> --draft-id <draft_id> --attachment-id <attachment_id>
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_drafts:DraftId'
- 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'
/v0/inboxes/{inbox_id}/drafts/{draft_id}/send:
post:
operationId: send
summary: Send Draft
description: '**CLI:**
```bash
agentmail inboxes:drafts send --inbox-id <inbox_id> --draft-id <draft_id>
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_inboxes:InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/type_drafts:DraftId'
- 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_messages:SendMessageResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ValidationErrorResponse'
'403':
description: Error response with status 403
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/type_:ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/type_messages:UpdateMessageRequest'
components:
schemas:
type_drafts:DraftAttachments:
type: array
items:
$ref: '#/components/schemas/type_attachments:Attachment'
description: Attachments in draft.
title: DraftAttachments
type_:After:
type: string
format: date-time
description: Timestamp after which to filter by.
title: After
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_drafts:DraftBcc:
type: array
items:
type: string
description: Addresses of BCC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftBcc
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_drafts:DraftCc:
type: array
items:
type: string
description: Addresses of CC recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftCc
type_messages:UpdateMessageRequest:
type: object
properties:
add_labels:
$ref: '#/components/schemas/type_messages:UpdateMessageLabels'
description: Label or labels to add to message.
remove_labels:
$ref: '#/components/schemas/type_messages:UpdateMessageLabels'
description: Label or labels to remove from message.
title: UpdateMessageRequest
type_drafts:CreateDraftRequest:
type: object
properties:
labels:
$ref: '#/components/schemas/type_drafts:DraftLabels'
reply_to:
$ref: '#/components/schemas/type_drafts:DraftReplyTo'
to:
$ref: '#/components/schemas/type_drafts:DraftTo'
cc:
$ref: '#/components/schemas/type_drafts:DraftCc'
bcc:
$ref: '#/components/schemas/type_drafts:DraftBcc'
subject:
$ref: '#/components/schemas/type_drafts:DraftSubject'
text:
$ref: '#/components/schemas/type_drafts:DraftText'
html:
$ref: '#/components/schemas/type_drafts:DraftHtml'
attachments:
type: array
items:
$ref: '#/components/schemas/type_attachments:SendAttachment'
description: Attachments to include in draft.
in_reply_to:
$ref: '#/components/schemas/type_drafts:DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/type_drafts:DraftForwardOf'
reply_all:
$ref: '#/components/schemas/type_drafts:DraftReplyAll'
send_at:
$ref: '#/components/schemas/type_drafts:DraftSendAt'
client_id:
$ref: '#/components/schemas/type_drafts:DraftClientId'
description: "Body for creating a draft. Supports plain, reply, reply-all, and forward\ndrafts:\n\n- **Plain draft:** supply `to`, `subject`, `text`, etc.\n- **Reply:** set `in_reply_to` to a message ID. Recipients, subject, and\n threading are derived from that message. Set `reply_all` to address the\n whole thread (you then cannot also pass `to`, `cc`, or `bcc`).\n- **Forward:** set `forward_of` to a message ID. The subject and threading\n are derived from the source message, whose body and attachments are\n merged in at send time.\n\n`in_reply_to` and `forward_of` are mutually exclusive, and reading the\nreferenced message requires `message_read` permission."
title: CreateDraftRequest
type_:Before:
type: string
format: date-time
description: Timestamp before which to filter by.
title: Before
type_drafts:DraftForwardOf:
type: string
description: ID of message being forwarded.
title: DraftForwardOf
type_attachments:AttachmentSize:
type: integer
description: Size of attachment in bytes.
title: AttachmentSize
type_drafts:DraftTo:
type: array
items:
type: string
description: Addresses of recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftTo
type_:Count:
type: integer
description: Number of items returned.
title: Count
type_drafts:UpdateDraftRequest:
type: object
properties:
reply_to:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftReplyTo'
- type: 'null'
to:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftTo'
- type: 'null'
cc:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftCc'
- type: 'null'
bcc:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftBcc'
- type: 'null'
subject:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftSubject'
- type: 'null'
text:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftText'
- type: 'null'
html:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftHtml'
- type: 'null'
add_attachments:
type: array
items:
$ref: '#/components/schemas/type_attachments:SendAttachment'
description: Attachments to add to the draft.
remove_attachments:
type: array
items:
$ref: '#/components/schemas/type_attachments:AttachmentId'
description: IDs of attachments to remove from the draft.
add_labels:
$ref: '#/components/schemas/type_drafts:DraftLabels'
description: Label or labels to add to the draft.
remove_labels:
$ref: '#/components/schemas/type_drafts:DraftLabels'
description: Label or labels to remove from the draft.
send_at:
oneOf:
- $ref: '#/components/schemas/type_drafts:DraftSendAt'
- type: 'null'
description: 'Edit fields on an existing draft. A draft''s kind (plain, reply, or forward)
is fixed at creation and cannot be changed here. Omitting a field leaves it
unchanged; passing `null` (or `[]` for a recipient field) clears it. Pass
`send_at` to schedule or reschedule the draft, or `null` to un-schedule it.'
title: UpdateDraftRequest
type_attachments:AttachmentContentId:
type: string
description: Content ID of attachment.
title: AttachmentContentId
type_attachments:SendAttachment:
type: object
properties:
filename:
$ref: '#/components/schemas/type_attachments:AttachmentFilename'
content_type:
$ref: '#/components/schemas/type_attachments:AttachmentContentType'
content_disposition:
$ref: '#/components/schemas/type_attachments:AttachmentContentDisposition'
content_id:
$ref: '#/components/schemas/type_attachments:AttachmentContentId'
content:
type: string
description: Base64 encoded content of attachment.
url:
type: string
description: URL to the attachment.
title: SendAttachment
type_:ErrorCode:
type: string
description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
title: ErrorCode
type_attachments:AttachmentId:
type: string
description: ID of attachment.
title: AttachmentId
type_attachments:AttachmentFilename:
type: string
description: Filename of attachment.
title: AttachmentFilename
type_attachments:AttachmentContentDisposition:
type: string
enum:
- inline
- attachment
description: Content disposition of attachment.
title: AttachmentContentDisposition
type_threads:ThreadId:
type: string
description: ID of thread.
title: ThreadId
type_drafts:DraftId:
type: string
description: ID of draft.
title: DraftId
type_inboxes:InboxId:
type: string
description: The ID of the inbox.
title: InboxId
type_:ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type_:ErrorName'
code:
$ref: '#/components/schemas/type_:ErrorCode'
message:
$ref: '#/components/schemas/type_:ErrorMessage'
errors:
description: Validation errors. Each entry has a path and a message identifying the invalid field.
fix:
$ref: '#/components/schemas/type_:ErrorFix'
docs:
$ref: '#/components/schemas/type_:ErrorDocs'
required:
- name
- errors
title: ValidationErrorResponse
type_drafts:DraftLabels:
type: array
items:
type: string
description: Labels of draft.
title: DraftLabels
type_:ErrorFix:
type: string
description: The concrete next action that resolves the error.
title: ErrorFix
type_:ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
type_drafts:DraftSendStatus:
type: string
enum:
- scheduled
- sending
- failed
description: Schedule send status of draft.
title: DraftSendStatus
type_drafts:DraftUpdatedAt:
type: string
format: date-time
description: Time at which draft was last updated.
title: DraftUpdatedAt
type_drafts:ListDraftsResponse:
type: object
properties:
count:
$ref: '#/components/schemas/type_:Count'
limit:
$ref: '#/components/schemas/type_:Limit'
next_page_token:
$ref: '#/components/schemas/type_:PageToken'
drafts:
type: array
items:
$ref: '#/components/schemas/type_drafts:DraftItem'
description: Ordered by `updated_at` descending.
required:
- count
- drafts
title: ListDraftsResponse
type_drafts:DraftReplyAll:
type: boolean
description: Reply to all recipients of the original message.
title: DraftReplyAll
type_messages:UpdateMessageLabels:
oneOf:
- type: string
- type: array
items:
type: string
description: Label or list of labels.
title: UpdateMessageLabels
type_drafts:DraftSubject:
type: string
description: Subject of draft.
title: DraftSubject
type_drafts:DraftText:
type: string
description: Plain text body of draft.
title: DraftText
type_:Limit:
type: integer
description: Limit of number of items returned.
title: Limit
type_drafts:DraftSendAt:
type: string
format: date-time
description: Time at which to schedule send draft.
title: DraftSendAt
type_drafts:DraftReplyTo:
type: array
items:
type: string
description: Reply-to addresses. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftReplyTo
type_messages:SendMessageResponse:
type: object
properties:
message_id:
$ref: '#/components/schemas/type_messages:MessageId'
thread_id:
$ref: '#/components/schemas/type_threads:ThreadId'
required:
- message_id
- thread_id
title: SendMessageResponse
type_:PageToken:
type: string
description: Page token for pagination.
title: PageToken
type_:ErrorName:
type: string
description: Name of error.
title: ErrorName
type_drafts:DraftItem:
type: object
properties:
inbox_id:
$ref: '#/components/schemas/type_inboxes:InboxId'
draft_id:
$ref: '#/components/schemas/type_drafts:DraftId'
labels:
$ref: '#/components/schemas/type_drafts:DraftLabels'
to:
$ref: '#/components/schemas/type_drafts:DraftTo'
cc:
$ref: '#/components/schemas/type_drafts:DraftCc'
bcc:
$ref: '#/components/schemas/type_drafts:DraftBcc'
subject:
$ref: '#/components/schemas/type_drafts:DraftSubject'
preview:
$ref: '#/components/schemas/type_drafts:DraftPreview'
attachments:
$ref: '#/components/schemas/type_drafts:DraftAttachments'
in_reply_to:
$ref: '#/components/schemas/type_drafts:DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/type_drafts:DraftForwardOf'
send_status:
$ref: '#/components/schemas/type_drafts:DraftSendStatus'
send_at:
$ref: '#/components/schemas/type_drafts:DraftSendAt'
updated_at:
$ref: '#/components/schemas/type_drafts:DraftUpdatedAt'
required:
- inbox_id
- draft_id
- labels
- updated_at
title: DraftItem
type_drafts:DraftPreview:
type: string
description: Text preview of draft.
title: DraftPreview
type_drafts:DraftClientId:
type: string
description: Client ID of draft.
title: DraftClientId
type_:ErrorDocs:
type: string
description: Link to the error reference entry for this code.
title: ErrorDocs
type_drafts:DraftHtml:
type: string
description: HTML body of draft.
title: DraftHtml
type_attachments:AttachmentContentType:
type: string
description: Content type of attachment.
title: AttachmentContentType
type_drafts:Draft:
type: object
properties:
inbox_id:
$ref: '#/components/schemas/type_inboxes:InboxId'
draft_id:
$ref: '#/components/schemas/type_drafts:DraftId'
client_id:
$ref: '#/components/schemas/type_drafts:DraftClientId'
labels:
$ref: '#/components/schemas/type_drafts:DraftLabels'
reply_to:
$ref: '#/components/schemas/type_drafts:DraftReplyTo'
to:
$ref: '#/components/schemas/type_drafts:DraftTo'
cc:
$ref: '#/components/schemas/type_drafts:DraftCc'
bcc:
$ref: '#/components/schemas/type_drafts:DraftBcc'
subject:
$ref: '#/components/schemas/type_drafts:DraftSubject'
preview:
$ref: '#/components/schemas/type_drafts:DraftPreview'
text:
$ref: '#/components/schemas/type_drafts:DraftText'
html:
$ref: '#/components/schemas/type_drafts:DraftHtml'
attachments:
$ref: '#/components/schemas/type_drafts:DraftAttachments'
in_reply_to:
$ref: '#/components/schemas/type_drafts:DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/type_drafts:DraftForwardOf'
references:
type: array
items:
type: string
description: IDs of previous messages in thread.
send_status:
$ref: '#/components/schemas/type_drafts:DraftSendStatus'
send_at:
$ref: '#/components/schemas/type_drafts:DraftSendAt'
updated_at:
$ref: '#/components/schemas/type_drafts:DraftUpdatedAt'
created_at:
type: string
format: date-time
description: Time at which draft was created.
required:
- inbox_id
- draft_id
- labels
- updated_at
- created_at
title: Draft
type_:ErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/type_:ErrorName'
code:
$ref: '#/components/schemas/type_:ErrorCode'
message:
$ref: '#/components/schemas/type_:ErrorMessage'
fix:
$ref: '#/components/schemas/type_:ErrorFix'
docs:
$ref: '#/components/schemas/type_:ErrorDocs'
required:
- name
- message
title: ErrorResponse
type_messages:MessageId:
type: string
description: ID of message.
title: MessageId
type_:Ascending:
type: boolean
description: Sort in ascending temporal order.
title: Ascending
type_drafts:DraftInReplyTo:
type: string
description: ID of message being replied to.
title: DraftInReplyTo
type_:Labels:
type: array
items:
type: string
description: Labels to filter by.
title: Labels
securitySchemes:
Bearer:
type: http
scheme: bearer