AgentMail inboxes > drafts API
The inboxes > drafts API from AgentMail — 4 operation(s) for inboxes > drafts.
The inboxes > drafts API from AgentMail — 4 operation(s) for inboxes > drafts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/agentmail-inboxes-drafts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Reference 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__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_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_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_drafts_DraftPreview:
type: string
description: Text preview of draft.
title: DraftPreview
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_attachments_AttachmentId:
type: string
description: ID of attachment.
title: AttachmentId
type_attachments_AttachmentSize:
type: integer
description: Size of attachment in bytes.
title: AttachmentSize
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_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_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_DraftId:
type: string
description: ID of draft.
title: DraftId
type_drafts_DraftText:
type: string
description: Plain text body of draft.
title: DraftText
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__ErrorFix:
type: string
description: The concrete next action that resolves the error.
title: ErrorFix
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__Count:
type: integer
description: Number of items returned.
title: Count
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_DraftInReplyTo:
type: string
description: ID of message being replied to.
title: DraftInReplyTo
type_attachments_AttachmentContentId:
type: string
description: Content ID of attachment.
title: AttachmentContentId
type__ErrorName:
type: string
description: Name of error.
title: ErrorName
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_drafts_DraftSendStatus:
type: string
enum:
- scheduled
- sending
- failed
description: Schedule send status of draft.
title: DraftSendStatus
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__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_drafts_DraftUpdatedAt:
type: string
format: date-time
description: Time at which draft was last updated.
title: DraftUpdatedAt
type_drafts_DraftReplyAll:
type: boolean
description: Reply to all recipients of the original message.
title: DraftReplyAll
type__ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
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_DraftClientId:
type: string
description: Client ID of draft.
title: DraftClientId
type__PageToken:
type: string
description: Page token for pagination.
title: PageToken
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_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_drafts_DraftForwardOf:
type: string
description: ID of message being forwarded.
title: DraftForwardOf
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_drafts_DraftLabels:
type: array
items:
type: string
description: Labels of draft.
title: DraftLabels
type__Limit:
type: integer
description: Limit of number of items returned.
title: Limit
type_drafts_DraftSubject:
type: string
description: Subject of draft.
title: DraftSubject
type_messages_UpdateMessageLabels:
oneOf:
- type: string
- type: array
items:
type: string
description: Label or list of labels.
title: UpdateMessageLabels
type_attachments_AttachmentFilename:
type: string
description: Filename of attachment.
title: AttachmentFilename
type__After:
type: string
format: date-time
description: Timestamp after which to filter by.
title: After
type_drafts_DraftAttachments:
type: array
items:
$ref: '#/components/schemas/type_attachments_Attachment'
description: Attachments in draft.
title: DraftAttachments
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_attachments_AttachmentContentDisposition:
type: string
enum:
- inline
- attachment
description: Content disposition of attachment.
title: AttachmentContentDisposition
type_drafts_DraftHtml:
type: string
description: HTML body of draft.
title: DraftHtml
type_inboxes_InboxId:
type: string
description: The ID of the inbox.
title: InboxId
type_attachments_AttachmentContentType:
type: string
description: Content type of attachment.
title: AttachmentContentType
type_drafts_DraftSendAt:
type: string
format: date-time
description: Time at which to schedule send draft.
title: DraftSendAt
type__Ascending:
type: boolean
description: Sort in ascending temporal order.
title: Ascending
type_threads_ThreadId:
type: string
description: ID of thread.
title: ThreadId
type__ErrorDocs:
type: string
description: Link to the error reference entry for this code.
title: ErrorDocs
securitySchemes:
Bearer:
type: http
scheme: bearer