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:agentmail-inboxes-drafts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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: inboxes_drafts_list
summary: List Drafts
description: '**CLI:**
```bash
agentmail inboxes drafts list --inbox-id
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/Limit'
- name: page_token
in: query
required: false
schema:
$ref: '#/components/schemas/PageToken'
- name: labels
in: query
required: false
schema:
$ref: '#/components/schemas/Labels'
- name: before
in: query
required: false
schema:
$ref: '#/components/schemas/Before'
- name: after
in: query
required: false
schema:
$ref: '#/components/schemas/After'
- name: ascending
in: query
required: false
schema:
$ref: '#/components/schemas/Ascending'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_ListDraftsResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
post:
operationId: inboxes_drafts_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 --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/inboxes_InboxId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_Draft'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_CreateDraftRequest'
security:
- Bearer: []
/v0/inboxes/{inbox_id}/drafts/{draft_id}:
get:
operationId: inboxes_drafts_get
summary: Get Draft
description: '**CLI:**
```bash
agentmail inboxes drafts get --inbox-id --draft-id
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/drafts_DraftId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_Draft'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
patch:
operationId: inboxes_drafts_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 --draft-id --subject "Updated subject"
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/drafts_DraftId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_Draft'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/drafts_UpdateDraftRequest'
security:
- Bearer: []
delete:
operationId: inboxes_drafts_delete
summary: Delete Draft
description: '**CLI:**
```bash
agentmail inboxes drafts delete --inbox-id --draft-id
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/drafts_DraftId'
responses:
'200':
description: Successful response
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
/v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}:
get:
operationId: inboxes_drafts_getAttachment
summary: Get Attachment
description: '**CLI:**
```bash
agentmail inboxes drafts get-attachment --inbox-id --draft-id --attachment-id
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/drafts_DraftId'
- name: attachment_id
in: path
required: true
schema:
$ref: '#/components/schemas/attachments_AttachmentId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/attachments_AttachmentResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Bearer: []
/v0/inboxes/{inbox_id}/drafts/{draft_id}/send:
post:
operationId: inboxes_drafts_send
summary: Send Draft
description: '**CLI:**
```bash
agentmail inboxes drafts send --inbox-id --draft-id
```'
tags:
- inboxes > drafts
parameters:
- name: inbox_id
in: path
required: true
schema:
$ref: '#/components/schemas/inboxes_InboxId'
- name: draft_id
in: path
required: true
schema:
$ref: '#/components/schemas/drafts_DraftId'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/messages_SendMessageResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'403':
description: Error response with status 403
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Error response with status 404
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Error response with status 409
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/messages_UpdateMessageRequest'
security:
- Bearer: []
components:
schemas:
drafts_ListDraftsResponse:
type: object
properties:
count:
$ref: '#/components/schemas/Count'
limit:
$ref: '#/components/schemas/Limit'
next_page_token:
$ref: '#/components/schemas/PageToken'
drafts:
type: array
items:
$ref: '#/components/schemas/drafts_DraftItem'
description: Ordered by `updated_at` descending.
required:
- count
- drafts
title: ListDraftsResponse
attachments_AttachmentSize:
type: integer
description: Size of attachment in bytes.
title: AttachmentSize
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
drafts_UpdateDraftRequest:
type: object
properties:
reply_to:
oneOf:
- $ref: '#/components/schemas/drafts_DraftReplyTo'
- type: 'null'
to:
oneOf:
- $ref: '#/components/schemas/drafts_DraftTo'
- type: 'null'
cc:
oneOf:
- $ref: '#/components/schemas/drafts_DraftCc'
- type: 'null'
bcc:
oneOf:
- $ref: '#/components/schemas/drafts_DraftBcc'
- type: 'null'
subject:
oneOf:
- $ref: '#/components/schemas/drafts_DraftSubject'
- type: 'null'
text:
oneOf:
- $ref: '#/components/schemas/drafts_DraftText'
- type: 'null'
html:
oneOf:
- $ref: '#/components/schemas/drafts_DraftHtml'
- type: 'null'
add_attachments:
type: array
items:
$ref: '#/components/schemas/attachments_SendAttachment'
description: Attachments to add to the draft.
remove_attachments:
type: array
items:
$ref: '#/components/schemas/attachments_AttachmentId'
description: IDs of attachments to remove from the draft.
add_labels:
$ref: '#/components/schemas/drafts_DraftLabels'
description: Label or labels to add to the draft.
remove_labels:
$ref: '#/components/schemas/drafts_DraftLabels'
description: Label or labels to remove from the draft.
send_at:
oneOf:
- $ref: '#/components/schemas/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
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
drafts_DraftId:
type: string
description: ID of draft.
title: DraftId
drafts_Draft:
type: object
properties:
inbox_id:
$ref: '#/components/schemas/inboxes_InboxId'
draft_id:
$ref: '#/components/schemas/drafts_DraftId'
client_id:
$ref: '#/components/schemas/drafts_DraftClientId'
labels:
$ref: '#/components/schemas/drafts_DraftLabels'
reply_to:
$ref: '#/components/schemas/drafts_DraftReplyTo'
to:
$ref: '#/components/schemas/drafts_DraftTo'
cc:
$ref: '#/components/schemas/drafts_DraftCc'
bcc:
$ref: '#/components/schemas/drafts_DraftBcc'
subject:
$ref: '#/components/schemas/drafts_DraftSubject'
preview:
$ref: '#/components/schemas/drafts_DraftPreview'
text:
$ref: '#/components/schemas/drafts_DraftText'
html:
$ref: '#/components/schemas/drafts_DraftHtml'
attachments:
$ref: '#/components/schemas/drafts_DraftAttachments'
in_reply_to:
$ref: '#/components/schemas/drafts_DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/drafts_DraftForwardOf'
references:
type: array
items:
type: string
description: IDs of previous messages in thread.
send_status:
$ref: '#/components/schemas/drafts_DraftSendStatus'
send_at:
$ref: '#/components/schemas/drafts_DraftSendAt'
updated_at:
$ref: '#/components/schemas/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
attachments_AttachmentContentDisposition:
type: string
enum:
- inline
- attachment
description: Content disposition of attachment.
title: AttachmentContentDisposition
attachments_AttachmentResponse:
type: object
properties:
attachment_id:
$ref: '#/components/schemas/attachments_AttachmentId'
filename:
$ref: '#/components/schemas/attachments_AttachmentFilename'
size:
$ref: '#/components/schemas/attachments_AttachmentSize'
content_type:
$ref: '#/components/schemas/attachments_AttachmentContentType'
content_disposition:
$ref: '#/components/schemas/attachments_AttachmentContentDisposition'
content_id:
$ref: '#/components/schemas/attachments_AttachmentContentId'
download_url:
type: string
description: Signed HTTPS CDN URL to download the attachment bytes. Retrieve a fresh URL when needed rather than storing it permanently.
text_url:
type: string
description: Signed HTTPS CDN URL to download extracted plain text, when available. Omitted when no extracted text is available. Expires at the same time as download_url.
expires_at:
type: string
format: date-time
description: Time at which download_url and text_url (when present) expire. Retrieve the attachment again to obtain fresh URLs.
required:
- attachment_id
- size
- download_url
- expires_at
title: AttachmentResponse
drafts_CreateDraftRequest:
type: object
properties:
labels:
$ref: '#/components/schemas/drafts_DraftLabels'
reply_to:
$ref: '#/components/schemas/drafts_DraftReplyTo'
to:
$ref: '#/components/schemas/drafts_DraftTo'
cc:
$ref: '#/components/schemas/drafts_DraftCc'
bcc:
$ref: '#/components/schemas/drafts_DraftBcc'
subject:
$ref: '#/components/schemas/drafts_DraftSubject'
text:
$ref: '#/components/schemas/drafts_DraftText'
html:
$ref: '#/components/schemas/drafts_DraftHtml'
attachments:
type: array
items:
$ref: '#/components/schemas/attachments_SendAttachment'
description: Attachments to include in draft.
in_reply_to:
$ref: '#/components/schemas/drafts_DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/drafts_DraftForwardOf'
reply_all:
$ref: '#/components/schemas/drafts_DraftReplyAll'
send_at:
$ref: '#/components/schemas/drafts_DraftSendAt'
client_id:
$ref: '#/components/schemas/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
drafts_DraftPreview:
type: string
description: Text preview of draft.
title: DraftPreview
Count:
type: integer
description: Number of items returned.
title: Count
ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ErrorName'
code:
$ref: '#/components/schemas/ErrorCode'
message:
$ref: '#/components/schemas/ErrorMessage'
errors:
description: Validation errors. Each entry has a path and a message identifying the invalid field.
fix:
$ref: '#/components/schemas/ErrorFix'
docs:
$ref: '#/components/schemas/ErrorDocs'
required:
- name
- errors
title: ValidationErrorResponse
drafts_DraftLabels:
type: array
items:
type: string
description: Labels of draft.
title: DraftLabels
After:
type: string
format: date-time
description: Timestamp after which to filter by.
title: After
messages_UpdateMessageLabels:
oneOf:
- type: string
- type: array
items:
type: string
description: Label or list of labels.
title: UpdateMessageLabels
ErrorDocs:
type: string
description: Link to the error reference entry for this code.
title: ErrorDocs
drafts_DraftForwardOf:
type: string
description: ID of message being forwarded.
title: DraftForwardOf
Before:
type: string
format: date-time
description: Timestamp before which to filter by.
title: Before
attachments_AttachmentId:
type: string
description: ID of attachment.
title: AttachmentId
drafts_DraftHtml:
type: string
description: HTML body of draft.
title: DraftHtml
attachments_Attachment:
type: object
properties:
attachment_id:
$ref: '#/components/schemas/attachments_AttachmentId'
filename:
$ref: '#/components/schemas/attachments_AttachmentFilename'
size:
$ref: '#/components/schemas/attachments_AttachmentSize'
content_type:
$ref: '#/components/schemas/attachments_AttachmentContentType'
content_disposition:
$ref: '#/components/schemas/attachments_AttachmentContentDisposition'
content_id:
$ref: '#/components/schemas/attachments_AttachmentContentId'
required:
- attachment_id
- size
title: Attachment
ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
drafts_DraftClientId:
type: string
description: Client ID of draft.
title: DraftClientId
inboxes_InboxId:
type: string
description: The ID of the inbox.
title: InboxId
drafts_DraftUpdatedAt:
type: string
format: date-time
description: Time at which draft was last updated.
title: DraftUpdatedAt
drafts_DraftInReplyTo:
type: string
description: ID of message being replied to.
title: DraftInReplyTo
attachments_AttachmentContentType:
type: string
description: Content type of attachment.
title: AttachmentContentType
drafts_DraftText:
type: string
description: Plain text body of draft.
title: DraftText
messages_MessageId:
type: string
description: ID of message.
title: MessageId
Labels:
type: array
items:
type: string
description: Labels to filter by.
title: Labels
drafts_DraftReplyAll:
type: boolean
description: Reply to all recipients of the original message.
title: DraftReplyAll
attachments_AttachmentContentId:
type: string
description: Content ID of attachment.
title: AttachmentContentId
messages_UpdateMessageRequest:
type: object
properties:
add_labels:
$ref: '#/components/schemas/messages_UpdateMessageLabels'
description: Label or labels to add to message.
remove_labels:
$ref: '#/components/schemas/messages_UpdateMessageLabels'
description: Label or labels to remove from message.
title: UpdateMessageRequest
drafts_DraftReplyTo:
type: array
items:
type: string
description: Reply-to addresses. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftReplyTo
drafts_DraftSendAt:
type: string
format: date-time
description: Time at which to schedule send draft.
title: DraftSendAt
drafts_DraftAttachments:
type: array
items:
$ref: '#/components/schemas/attachments_Attachment'
description: Attachments in draft.
title: DraftAttachments
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
ErrorFix:
type: string
description: The concrete next action that resolves the error.
title: ErrorFix
Limit:
type: integer
description: Limit of number of items returned.
title: Limit
drafts_DraftTo:
type: array
items:
type: string
description: Addresses of recipients. In format `username@domain.com` or `Display Name <username@domain.com>`.
title: DraftTo
drafts_DraftItem:
type: object
properties:
inbox_id:
$ref: '#/components/schemas/inboxes_InboxId'
draft_id:
$ref: '#/components/schemas/drafts_DraftId'
labels:
$ref: '#/components/schemas/drafts_DraftLabels'
to:
$ref: '#/components/schemas/drafts_DraftTo'
cc:
$ref: '#/components/schemas/drafts_DraftCc'
bcc:
$ref: '#/components/schemas/drafts_DraftBcc'
subject:
$ref: '#/components/schemas/drafts_DraftSubject'
preview:
$ref: '#/components/schemas/drafts_DraftPreview'
attachments:
$ref: '#/components/schemas/drafts_DraftAttachments'
in_reply_to:
$ref: '#/components/schemas/drafts_DraftInReplyTo'
forward_of:
$ref: '#/components/schemas/drafts_DraftForwardOf'
send_status:
$ref: '#/components/schemas/drafts_DraftSendStatus'
send_at:
$ref: '#/components/schemas/drafts_DraftSendAt'
updated_at:
$ref: '#/components/schemas/drafts_DraftUpdatedAt'
required:
- inbox_id
- draft_id
- labels
- updated_at
title: DraftItem
drafts_DraftSubject:
type: string
description: Subject of draft.
title: DraftSubject
Ascending:
type: boolean
description: Sort in ascending temporal order.
title: Ascending
ErrorName:
type: string
description: Name of error.
title: ErrorName
attachments_AttachmentFilename:
type: string
description: Filename of attachment.
title: AttachmentFilename
threads_ThreadId:
type: string
description: ID of thread.
title: ThreadId
messages_SendMessageResponse:
type: object
properties:
message_id:
$ref: '#/components/schemas/messages_MessageId'
thread_id:
$ref: '#/components/schemas/threads_ThreadId'
required:
- message_id
- thread_id
title: SendMessageResponse
drafts_DraftSendStatus:
type: string
enum:
- scheduled
- sending
- failed
description: Schedule send status of draft.
title: DraftSendStatus
PageToken:
type: string
description: Page token for pagination.
title: PageToken
ErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ErrorName'
code:
$ref: '#/components/schemas/ErrorCode'
message:
$ref: '#/components/schemas/ErrorMessage'
fix:
$ref: '#/components/schemas/ErrorFix'
docs:
$ref: '#/components/schemas/ErrorDocs'
required:
- name
- message
title: ErrorResponse
attachments_SendAttachment:
type: object
properties:
filename:
$ref: '#/components/schemas/attachments_AttachmentFilename'
content_type:
$ref: '#/components/schemas/attachments_AttachmentContentType'
content_disposition:
$ref: '#/components/schemas/attachments_AttachmentContentDisposition'
content_id:
$ref: '#/components/schemas/attachments_AttachmentContentId'
content:
type: string
description: Base64 encoded content of the attachment. The entire request, including the message body and all attachments, is limited to 6 MB.
url:
type: string
description: 'URL that AgentMail can download without custom authentication headers or cookies.
Redirects and pre-signed URLs are supported, and the final response must be a
successful 2xx response. Keep URL-backed attachments around 30 MB total per message.'
description: Provide either `content` or `url` for each attachment.
title: SendAttachment
securitySchemes:
Bearer:
type: http
scheme: bearer
x-provenance:
method: harvested
publisher: AgentMail
source: https://docs.agentmail.to/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)