From 3b28e885c00f7dbd62ddf65d12064c3d62140a93 Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Thu, 13 Nov 2025 17:43:22 -0500 Subject: [PATCH 1/3] adding explanation in API reference --- agentmail_api_descriptions.md | 215 +++++++++++++++++++++++ api_documentation_progress.md | 118 +++++++++++++ fern/definition/api-keys.yml | 3 + fern/definition/domains.yml | 6 + fern/definition/drafts.yml | 2 + fern/definition/inboxes/__package__.yml | 5 + fern/definition/inboxes/drafts.yml | 6 + fern/definition/inboxes/messages.yml | 7 + fern/definition/inboxes/metrics.yml | 1 + fern/definition/inboxes/threads.yml | 4 + fern/definition/pods/__package__.yml | 4 + fern/definition/pods/domains.yml | 3 + fern/definition/pods/drafts.yml | 2 + fern/definition/pods/inboxes.yml | 4 + fern/definition/pods/threads.yml | 3 + fern/definition/threads.yml | 3 + fern/definition/webhooks/__package__.yml | 4 + fern/definition/websockets.yml | 1 + 18 files changed, 391 insertions(+) create mode 100644 agentmail_api_descriptions.md create mode 100644 api_documentation_progress.md diff --git a/agentmail_api_descriptions.md b/agentmail_api_descriptions.md new file mode 100644 index 0000000..94185c4 --- /dev/null +++ b/agentmail_api_descriptions.md @@ -0,0 +1,215 @@ +# AgentMail API Reference - Endpoint Descriptions + +## Inboxes (邮箱管理) + +### List Inboxes +**Endpoint:** `GET /inboxes` +**Description:** Retrieves a paginated list of all inboxes in your AgentMail account, ordered by creation date descending. + +### Create Inbox +**Endpoint:** `POST /inboxes` +**Description:** Creates a new email inbox with a specified username and domain for your AI agent to send and receive emails. + +### Get Inbox +**Endpoint:** `GET /inboxes/{inbox_id}` +**Description:** Retrieves detailed information about a specific inbox including its configuration, status, and metadata. + +### Update Inbox +**Endpoint:** `PATCH /inboxes/{inbox_id}` +**Description:** Updates the configuration or settings of an existing inbox such as display name or forwarding rules. + +### Delete Inbox +**Endpoint:** `DELETE /inboxes/{inbox_id}` +**Description:** Permanently deletes an inbox and all associated messages, threads, and drafts. + +--- + +## Threads (邮件线程管理) + +### List Threads +**Endpoint:** `GET /inboxes/{inbox_id}/threads` +**Description:** Returns all email conversation threads in a specific inbox, grouped by related messages. + +### Get Thread +**Endpoint:** `GET /inboxes/{inbox_id}/threads/{thread_id}` +**Description:** Retrieves a complete email thread including all messages, participants, and conversation history. + +### List All Threads +**Endpoint:** `GET /threads` +**Description:** Retrieves threads across all inboxes in your account for a global view of email conversations. + +--- + +## Messages (消息管理) + +### List Messages +**Endpoint:** `GET /inboxes/{inbox_id}/messages` +**Description:** Returns all email messages in a specific inbox with options to filter by thread, date, or status. + +### Get Message +**Endpoint:** `GET /inboxes/{inbox_id}/messages/{message_id}` +**Description:** Retrieves the full content of a specific email message including body, headers, and attachments. + +### Send Message +**Endpoint:** `POST /inboxes/{inbox_id}/messages` +**Description:** Sends a new email message from the specified inbox to one or more recipients. + +### Reply to Message +**Endpoint:** `POST /inboxes/{inbox_id}/messages/{message_id}/reply` +**Description:** Sends a reply to an existing message, automatically maintaining the email thread and conversation context. + +### Update Message +**Endpoint:** `PATCH /inboxes/{inbox_id}/messages/{message_id}` +**Description:** Updates message metadata such as read status, labels, or custom flags. + +--- + +## Drafts (草稿管理) + +### List Drafts +**Endpoint:** `GET /inboxes/{inbox_id}/drafts` +**Description:** Retrieves all saved email drafts in a specific inbox that haven't been sent yet. + +### Get Draft +**Endpoint:** `GET /inboxes/{inbox_id}/drafts/{draft_id}` +**Description:** Retrieves the content and metadata of a specific email draft for editing or review. + +### Create Draft +**Endpoint:** `POST /inboxes/{inbox_id}/drafts` +**Description:** Creates a new email draft with recipient, subject, and body content that can be edited before sending. + +### Update Draft +**Endpoint:** `PATCH /inboxes/{inbox_id}/drafts/{draft_id}` +**Description:** Updates the content or recipients of an existing draft before it is sent. + +### Send Draft +**Endpoint:** `POST /inboxes/{inbox_id}/drafts/{draft_id}/send` +**Description:** Converts a draft into a sent message, delivering it to the specified recipients. + +### Delete Draft +**Endpoint:** `DELETE /inboxes/{inbox_id}/drafts/{draft_id}` +**Description:** Permanently removes a draft from the inbox without sending it. + +--- + +## Domains (域名管理) + +### List Domains +**Endpoint:** `GET /domains` +**Description:** Retrieves all custom domains configured for your AgentMail account. + +### Get Domain +**Endpoint:** `GET /domains/{domain}` +**Description:** Returns detailed information about a specific domain including verification status and DNS records. + +### Add Domain +**Endpoint:** `POST /domains` +**Description:** Adds a new custom domain to your account for creating branded email addresses for your agents. + +### Verify Domain +**Endpoint:** `POST /domains/{domain}/verify` +**Description:** Initiates domain verification process to confirm ownership through DNS records. + +### Get Zone File +**Endpoint:** `GET /domains/{domain}/zone-file` +**Description:** Returns the DNS zone file configuration needed for proper email delivery (SPF, DKIM, DMARC records). + +### Delete Domain +**Endpoint:** `DELETE /domains/{domain}` +**Description:** Removes a custom domain from your account and disables any inboxes using that domain. + +--- + +## Webhooks (Webhook事件管理) + +### List Webhooks +**Endpoint:** `GET /webhooks` +**Description:** Returns all configured webhook endpoints that receive real-time notifications for email events. + +### Get Webhook +**Endpoint:** `GET /webhooks/{webhook_id}` +**Description:** Retrieves configuration details for a specific webhook including URL, events, and status. + +### Create Webhook +**Endpoint:** `POST /webhooks` +**Description:** Creates a new webhook to receive real-time HTTP callbacks when email events occur (e.g., message received, sent). + +### Update Webhook +**Endpoint:** `PATCH /webhooks/{webhook_id}` +**Description:** Updates webhook configuration such as target URL, subscribed events, or authentication. + +### Delete Webhook +**Endpoint:** `DELETE /webhooks/{webhook_id}` +**Description:** Removes a webhook endpoint and stops sending event notifications to that URL. + +### Test Webhook +**Endpoint:** `POST /webhooks/{webhook_id}/test` +**Description:** Sends a test event to the webhook URL to verify the endpoint is properly configured and responding. + +--- + +## Websockets (实时连接) + +### Connect +**Endpoint:** `WSS wss://ws.agentmail.to/v0` +**Description:** Establishes a WebSocket connection for real-time bidirectional communication to receive instant email notifications and events. + +### Subscribe +**Message Type:** `subscribe` +**Description:** Subscribes to real-time updates for specific inbox IDs through the WebSocket connection. + +### Message Received +**Event Type:** `message_received` +**Description:** Real-time event pushed through WebSocket when a new email message arrives in subscribed inboxes. + +--- + +## Labels (标签管理) + +### List Labels +**Endpoint:** `GET /inboxes/{inbox_id}/labels` +**Description:** Returns all custom labels created for organizing messages in a specific inbox. + +### Create Label +**Endpoint:** `POST /inboxes/{inbox_id}/labels` +**Description:** Creates a new custom label for categorizing and organizing email messages. + +### Apply Label +**Endpoint:** `POST /inboxes/{inbox_id}/messages/{message_id}/labels` +**Description:** Applies one or more labels to a specific message for organization and filtering. + +--- + +## Attachments (附件管理) + +### List Attachments +**Endpoint:** `GET /inboxes/{inbox_id}/messages/{message_id}/attachments` +**Description:** Returns metadata for all file attachments included in a specific email message. + +### Get Attachment +**Endpoint:** `GET /inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}` +**Description:** Downloads the binary content of a specific email attachment. + +### Upload Attachment +**Endpoint:** `POST /inboxes/{inbox_id}/attachments` +**Description:** Uploads a file to be attached to a draft or outgoing message before sending. + +--- + +## Pods (多租户管理) + +### List Pods +**Endpoint:** `GET /pods` +**Description:** Retrieves all pod configurations for multi-tenant applications, allowing isolation of inboxes by customer or project. + +### Create Pod +**Endpoint:** `POST /pods` +**Description:** Creates a new pod for isolating email resources in multi-tenant architecture. + +### Get Pod +**Endpoint:** `GET /pods/{pod_id}` +**Description:** Returns configuration and resource information for a specific pod. + +### Delete Pod +**Endpoint:** `DELETE /pods/{pod_id}` +**Description:** Removes a pod and all associated inboxes, messages, and resources within that tenant boundary. diff --git a/api_documentation_progress.md b/api_documentation_progress.md new file mode 100644 index 0000000..2f5ca7f --- /dev/null +++ b/api_documentation_progress.md @@ -0,0 +1,118 @@ +# API Documentation Progress Tracker + +## Task: Add `docs:` fields to all Fern API endpoints + +### Summary +- **Total Endpoints**: 67 endpoints + 1 WebSocket channel +- **Files to Update**: 15 files in `fern/definition/` +- **Status**: ✅ **COMPLETE** - All documentation re-added successfully after git recovery! + +--- + +## Phase 1: Core Endpoints (High Priority) + +### Inboxes (`fern/definition/inboxes/__package__.yml`) - 5 endpoints +- [x] list - "List Inboxes" +- [x] get - "Get Inbox" +- [x] create - "Create Inbox" +- [x] update - "Update Inbox" +- [x] delete - "Delete Inbox" + +### Messages (`fern/definition/inboxes/messages.yml`) - 7 endpoints +- [x] list - "List Messages" +- [x] get - "Get Message" +- [x] getAttachment - "Get Attachment" +- [x] getRaw - "Get Raw Message" +- [x] send - "Send Message" +- [x] reply - "Reply To Message" +- [x] update - "Update Message" + +### Threads - Inbox-scoped (`fern/definition/inboxes/threads.yml`) - 4 endpoints +- [x] list - "List Threads" +- [x] get - "Get Thread" +- [x] getAttachment - "Get Attachment" +- [x] delete - "Delete Thread" + +### Threads - Global (`fern/definition/threads.yml`) - 3 endpoints +- [x] list - "List Threads" +- [x] get - "Get Thread" +- [x] getAttachment - "Get Attachment" + +--- + +## Phase 2: Communication Features (Medium Priority) + +### Drafts - Inbox-scoped (`fern/definition/inboxes/drafts.yml`) - 6 endpoints +- [x] list - "List Drafts" +- [x] get - "Get Draft" +- [x] create - "Create Draft" +- [x] update - "Update Draft" +- [x] send - "Send Draft" +- [x] delete - "Delete Draft" + +### Drafts - Global (`fern/definition/drafts.yml`) - 2 endpoints +- [x] list - "List Drafts" +- [x] get - "Get Draft" + +### Domains (`fern/definition/domains.yml`) - 6 endpoints +- [x] list - "List Domains" +- [x] get - "Get Domain" +- [x] getZoneFile - "Get Zone File" +- [x] create - "Create Domain" +- [x] delete - "Delete Domain" +- [x] verify - "Verify Domain" + +### Webhooks (`fern/definition/webhooks/__package__.yml`) - 4 endpoints +- [x] list - "List Webhooks" +- [x] get - "Get Webhook" +- [x] create - "Create Webhook" +- [x] delete - "Delete Webhook" + +--- + +## Phase 3: Administrative Features (Lower Priority) + +### API Keys (`fern/definition/api-keys.yml`) - 3 endpoints +- [x] list - "List API Keys" +- [x] create - "Create API Key" +- [x] delete - "Delete API Key" + +### Pods (`fern/definition/pods/__package__.yml`) - 4 endpoints +- [x] list - "List Pods" +- [x] get - "Get Pod" +- [x] create - "Create Pod" +- [x] delete - "Delete Pod" + +### Pods - Inboxes (`fern/definition/pods/inboxes.yml`) - 4 endpoints +- [x] list - "List Inboxes" +- [x] get - "Get Inbox" +- [x] create - "Create Inbox" +- [x] delete - "Delete Inbox" + +### Pods - Threads (`fern/definition/pods/threads.yml`) - 3 endpoints +- [x] list - "List Threads" +- [x] get - "Get Thread" +- [x] getAttachment - "Get Attachment" + +### Pods - Drafts (`fern/definition/pods/drafts.yml`) - 2 endpoints +- [x] list - "List Drafts" +- [x] get - "Get Draft" + +### Pods - Domains (`fern/definition/pods/domains.yml`) - 3 endpoints +- [x] list - "List Domains" +- [x] create - "Create Domain" +- [x] delete - "Delete Domain" + +### Metrics (`fern/definition/inboxes/metrics.yml`) - 1 endpoint +- [x] get - "List Metrics" + +### WebSockets (`fern/definition/websockets.yml`) - 1 channel +- [x] Connect - "Connect" (WebSocket channel) + +--- + +## Notes +- Documentation format: Place `docs:` field directly below `display-name:` +- Keep descriptions concise (1-2 sentences) +- Use present tense, active voice +- Focus on what the endpoint does and when to use it \ No newline at end of file diff --git a/fern/definition/api-keys.yml b/fern/definition/api-keys.yml index 831e540..9840100 100644 --- a/fern/definition/api-keys.yml +++ b/fern/definition/api-keys.yml @@ -62,6 +62,7 @@ service: method: GET path: "" display-name: List API Keys + docs: Retrieves all API keys configured for authenticating with the AgentMail API. request: name: ListApiKeysRequest query-parameters: @@ -73,6 +74,7 @@ service: method: POST path: "" display-name: Create API Key + docs: Creates a new API key for authenticating API requests with a specified name. request: CreateApiKeyRequest response: CreateApiKeyResponse errors: @@ -82,6 +84,7 @@ service: method: DELETE path: /{api_key} display-name: Delete API Key + docs: Revokes an API key, preventing it from being used for authentication. path-parameters: api_key: ApiKeyId errors: diff --git a/fern/definition/domains.yml b/fern/definition/domains.yml index a84ecf5..badc5ad 100644 --- a/fern/definition/domains.yml +++ b/fern/definition/domains.yml @@ -112,6 +112,7 @@ service: method: GET path: "" display-name: List Domains + docs: Retrieves all custom domains configured for your AgentMail account. request: name: ListDomainsRequest query-parameters: @@ -123,6 +124,7 @@ service: method: GET path: /{domain_id} display-name: Get Domain + docs: Returns detailed information about a specific domain including verification status and DNS records. path-parameters: domain_id: DomainId response: Domain @@ -133,6 +135,7 @@ service: method: GET path: /{domain_id}/zone-file display-name: Get Zone File + docs: Returns the DNS zone file configuration needed for proper email delivery (SPF, DKIM, DMARC records). path-parameters: domain_id: DomainId response: file @@ -143,6 +146,7 @@ service: method: POST path: "" display-name: Create Domain + docs: Adds a new custom domain to your account for creating branded email addresses for your agents. request: CreateDomainRequest response: Domain errors: @@ -152,6 +156,7 @@ service: method: DELETE path: /{domain_id} display-name: Delete Domain + docs: Removes a custom domain from your account and disables any inboxes using that domain. path-parameters: domain_id: DomainId errors: @@ -161,6 +166,7 @@ service: method: POST path: /{domain_id}/verify display-name: Verify Domain + docs: Initiates domain verification process to confirm ownership through DNS records. path-parameters: domain_id: DomainId errors: diff --git a/fern/definition/drafts.yml b/fern/definition/drafts.yml index ab94cc6..a36c474 100644 --- a/fern/definition/drafts.yml +++ b/fern/definition/drafts.yml @@ -163,6 +163,7 @@ service: method: GET path: "" display-name: List Drafts + docs: Retrieves all saved email drafts across all inboxes in your account. request: name: ListDraftsRequest query-parameters: @@ -180,6 +181,7 @@ service: method: GET path: /{draft_id} display-name: Get Draft + docs: Retrieves a specific draft from any inbox with its full content and metadata. path-parameters: draft_id: DraftId response: Draft diff --git a/fern/definition/inboxes/__package__.yml b/fern/definition/inboxes/__package__.yml index 5a17df4..92ca9ee 100644 --- a/fern/definition/inboxes/__package__.yml +++ b/fern/definition/inboxes/__package__.yml @@ -70,6 +70,7 @@ service: method: GET path: "" display-name: List Inboxes + docs: Retrieves a paginated list of all inboxes in your AgentMail account, ordered by creation date descending. request: name: ListInboxesRequest query-parameters: @@ -81,6 +82,7 @@ service: method: GET path: /{inbox_id} display-name: Get Inbox + docs: Retrieves detailed information about a specific inbox including its configuration, status, and metadata. path-parameters: inbox_id: InboxId response: Inbox @@ -91,6 +93,7 @@ service: method: POST path: "" display-name: Create Inbox + docs: Creates a new email inbox with a specified username and domain for your AI agent to send and receive emails. request: CreateInboxRequest response: Inbox errors: @@ -100,6 +103,7 @@ service: method: PATCH path: /{inbox_id} display-name: Update Inbox + docs: Updates the configuration or settings of an existing inbox such as display name or forwarding rules. path-parameters: inbox_id: InboxId request: UpdateInboxRequest @@ -111,6 +115,7 @@ service: method: DELETE path: /{inbox_id} display-name: Delete Inbox + docs: Permanently deletes an inbox and all associated messages, threads, and drafts. path-parameters: inbox_id: InboxId errors: diff --git a/fern/definition/inboxes/drafts.yml b/fern/definition/inboxes/drafts.yml index 6d4a515..d880203 100644 --- a/fern/definition/inboxes/drafts.yml +++ b/fern/definition/inboxes/drafts.yml @@ -18,6 +18,7 @@ service: method: GET path: "" display-name: List Drafts + docs: Retrieves all saved email drafts in a specific inbox that haven't been sent yet. request: name: ListDraftsRequest query-parameters: @@ -35,6 +36,7 @@ service: method: GET path: /{draft_id} display-name: Get Draft + docs: Retrieves the content and metadata of a specific email draft for editing or review. path-parameters: draft_id: drafts.DraftId response: drafts.Draft @@ -45,6 +47,7 @@ service: method: POST path: "" display-name: Create Draft + docs: Creates a new email draft with recipient, subject, and body content that can be edited before sending. request: drafts.CreateDraftRequest response: drafts.Draft errors: @@ -54,6 +57,7 @@ service: method: PATCH path: /{draft_id} display-name: Update Draft + docs: Updates the content or recipients of an existing draft before it is sent. path-parameters: draft_id: drafts.DraftId request: drafts.UpdateDraftRequest @@ -65,6 +69,7 @@ service: method: POST path: /{draft_id}/send display-name: Send Draft + docs: Converts a draft into a sent message, delivering it to the specified recipients. path-parameters: draft_id: drafts.DraftId request: messages.UpdateMessageRequest @@ -78,6 +83,7 @@ service: method: DELETE path: /{draft_id} display-name: Delete Draft + docs: Permanently removes a draft from the inbox without sending it. path-parameters: draft_id: drafts.DraftId errors: diff --git a/fern/definition/inboxes/messages.yml b/fern/definition/inboxes/messages.yml index 4b7b5c3..a79c225 100644 --- a/fern/definition/inboxes/messages.yml +++ b/fern/definition/inboxes/messages.yml @@ -18,6 +18,7 @@ service: method: GET path: "" display-name: List Messages + docs: Returns all email messages in a specific inbox with options to filter by thread, date, or status. request: name: ListMessagesRequest query-parameters: @@ -35,6 +36,7 @@ service: method: GET path: /{message_id} display-name: Get Message + docs: Retrieves the full content of a specific email message including body, headers, and attachments. path-parameters: message_id: messages.MessageId response: messages.Message @@ -45,6 +47,7 @@ service: method: GET path: /{message_id}/attachments/{attachment_id} display-name: Get Attachment + docs: Downloads the binary content of a specific email attachment. path-parameters: message_id: messages.MessageId attachment_id: attachments.AttachmentId @@ -56,6 +59,7 @@ service: method: GET path: /{message_id}/raw display-name: Get Raw Message + docs: Returns the raw email message content including all headers and MIME parts. path-parameters: message_id: messages.MessageId response: file @@ -66,6 +70,7 @@ service: method: POST path: /send display-name: Send Message + docs: Sends a new email message from the specified inbox to one or more recipients. request: messages.SendMessageRequest response: messages.SendMessageResponse errors: @@ -77,6 +82,7 @@ service: method: POST path: /{message_id}/reply display-name: Reply To Message + docs: Sends a reply to an existing message, automatically maintaining the email thread and conversation context. path-parameters: message_id: messages.MessageId request: messages.ReplyToMessageRequest @@ -90,6 +96,7 @@ service: method: PATCH path: /{message_id} display-name: Update Message + docs: Updates message metadata such as read status, labels, or custom flags. path-parameters: message_id: messages.MessageId request: messages.UpdateMessageRequest diff --git a/fern/definition/inboxes/metrics.yml b/fern/definition/inboxes/metrics.yml index f3c1616..6a8426f 100644 --- a/fern/definition/inboxes/metrics.yml +++ b/fern/definition/inboxes/metrics.yml @@ -17,6 +17,7 @@ service: method: GET path: "" display-name: List Metrics + docs: Retrieves email metrics and statistics for a specific inbox within a given time range. request: name: ListInboxMetricsRequest query-parameters: diff --git a/fern/definition/inboxes/threads.yml b/fern/definition/inboxes/threads.yml index 3709a9b..f4a74a5 100644 --- a/fern/definition/inboxes/threads.yml +++ b/fern/definition/inboxes/threads.yml @@ -18,6 +18,7 @@ service: method: GET path: "" display-name: List Threads + docs: Returns all email conversation threads in a specific inbox, grouped by related messages. request: name: ListThreadsRequest query-parameters: @@ -35,6 +36,7 @@ service: method: GET path: /{thread_id} display-name: Get Thread + docs: Retrieves a complete email thread including all messages, participants, and conversation history. path-parameters: thread_id: threads.ThreadId response: threads.Thread @@ -45,6 +47,7 @@ service: method: GET path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment + docs: Downloads an attachment from any message within the specified thread. path-parameters: thread_id: threads.ThreadId attachment_id: attachments.AttachmentId @@ -56,6 +59,7 @@ service: method: DELETE path: /{thread_id} display-name: Delete Thread + docs: Permanently deletes an entire email thread and all its associated messages. path-parameters: thread_id: threads.ThreadId errors: diff --git a/fern/definition/pods/__package__.yml b/fern/definition/pods/__package__.yml index 672a88b..7658870 100644 --- a/fern/definition/pods/__package__.yml +++ b/fern/definition/pods/__package__.yml @@ -58,6 +58,7 @@ service: method: GET path: "" display-name: List Pods + docs: Retrieves all pod configurations for multi-tenant applications, allowing isolation of inboxes by customer or project. request: name: ListPodsRequest query-parameters: @@ -69,6 +70,7 @@ service: method: GET path: /{pod_id} display-name: Get Pod + docs: Returns configuration and resource information for a specific pod. path-parameters: pod_id: PodId response: Pod @@ -79,6 +81,7 @@ service: method: POST path: "" display-name: Create Pod + docs: Creates a new pod for isolating email resources in multi-tenant architecture. request: CreatePodRequest response: Pod errors: @@ -88,6 +91,7 @@ service: method: DELETE path: /{pod_id} display-name: Delete Pod + docs: Removes a pod and all associated inboxes, messages, and resources within that tenant boundary. path-parameters: pod_id: PodId errors: diff --git a/fern/definition/pods/domains.yml b/fern/definition/pods/domains.yml index 5fee3a8..490d483 100644 --- a/fern/definition/pods/domains.yml +++ b/fern/definition/pods/domains.yml @@ -17,6 +17,7 @@ service: method: GET path: "" display-name: List Domains + docs: Retrieves all custom domains configured within a specific pod for tenant-specific email addresses. request: name: ListDomainsRequest query-parameters: @@ -34,6 +35,7 @@ service: method: POST path: "" display-name: Create Domain + docs: Adds a new custom domain to a specific pod for creating tenant-isolated email addresses. request: domains.CreateDomainRequest response: domains.Domain errors: @@ -43,6 +45,7 @@ service: method: DELETE path: /{domain_id} display-name: Delete Domain + docs: Removes a custom domain from a specific pod and disables associated inboxes. path-parameters: domain_id: domains.DomainId errors: diff --git a/fern/definition/pods/drafts.yml b/fern/definition/pods/drafts.yml index ea267d9..2609e84 100644 --- a/fern/definition/pods/drafts.yml +++ b/fern/definition/pods/drafts.yml @@ -17,6 +17,7 @@ service: method: GET path: "" display-name: List Drafts + docs: Retrieves all email drafts across all inboxes within a specific pod. request: name: ListDraftsRequest query-parameters: @@ -34,6 +35,7 @@ service: method: GET path: /{draft_id} display-name: Get Draft + docs: Retrieves a specific draft from any inbox within the specified pod. path-parameters: draft_id: drafts.DraftId response: drafts.Draft diff --git a/fern/definition/pods/inboxes.yml b/fern/definition/pods/inboxes.yml index 647b43f..7cb81e2 100644 --- a/fern/definition/pods/inboxes.yml +++ b/fern/definition/pods/inboxes.yml @@ -17,6 +17,7 @@ service: method: GET path: "" display-name: List Inboxes + docs: Retrieves all inboxes within a specific pod for multi-tenant email isolation. request: name: ListInboxesRequest query-parameters: @@ -34,6 +35,7 @@ service: method: GET path: /{inbox_id} display-name: Get Inbox + docs: Retrieves detailed information about a specific inbox within a pod. path-parameters: inbox_id: inboxes.InboxId response: inboxes.Inbox @@ -44,6 +46,7 @@ service: method: POST path: "" display-name: Create Inbox + docs: Creates a new email inbox within a specific pod for tenant-isolated communication. request: inboxes.CreateInboxRequest response: inboxes.Inbox errors: @@ -53,6 +56,7 @@ service: method: DELETE path: /{inbox_id} display-name: Delete Inbox + docs: Permanently deletes an inbox from a specific pod along with all its messages. path-parameters: inbox_id: inboxes.InboxId errors: diff --git a/fern/definition/pods/threads.yml b/fern/definition/pods/threads.yml index c07c134..a005206 100644 --- a/fern/definition/pods/threads.yml +++ b/fern/definition/pods/threads.yml @@ -18,6 +18,7 @@ service: method: GET path: "" display-name: List Threads + docs: Retrieves all email threads across all inboxes within a specific pod. request: name: ListThreadsRequest query-parameters: @@ -35,6 +36,7 @@ service: method: GET path: /{thread_id} display-name: Get Thread + docs: Retrieves a complete email thread from any inbox within the specified pod. path-parameters: thread_id: threads.ThreadId response: threads.Thread @@ -45,6 +47,7 @@ service: method: GET path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment + docs: Downloads an attachment from any message within a thread in the specified pod. path-parameters: thread_id: threads.ThreadId attachment_id: attachments.AttachmentId diff --git a/fern/definition/threads.yml b/fern/definition/threads.yml index 5d87f34..cfcd975 100644 --- a/fern/definition/threads.yml +++ b/fern/definition/threads.yml @@ -127,6 +127,7 @@ service: method: GET path: "" display-name: List Threads + docs: Retrieves threads across all inboxes in your account for a global view of email conversations. request: name: ListThreadsRequest query-parameters: @@ -144,6 +145,7 @@ service: method: GET path: /{thread_id} display-name: Get Thread + docs: Retrieves a complete email thread from any inbox with all messages and conversation history. path-parameters: thread_id: ThreadId response: Thread @@ -154,6 +156,7 @@ service: method: GET path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment + docs: Downloads an attachment from any message within the thread across all inboxes. path-parameters: thread_id: ThreadId attachment_id: attachments.AttachmentId diff --git a/fern/definition/webhooks/__package__.yml b/fern/definition/webhooks/__package__.yml index 03f2a99..5a63926 100644 --- a/fern/definition/webhooks/__package__.yml +++ b/fern/definition/webhooks/__package__.yml @@ -67,6 +67,7 @@ service: method: GET path: "" display-name: List Webhooks + docs: Returns all configured webhook endpoints that receive real-time notifications for email events. request: name: ListWebhooksRequest query-parameters: @@ -78,6 +79,7 @@ service: method: GET path: /{webhook_id} display-name: Get Webhook + docs: Retrieves configuration details for a specific webhook including URL, events, and status. path-parameters: webhook_id: WebhookId response: Webhook @@ -88,6 +90,7 @@ service: method: POST path: "" display-name: Create Webhook + docs: Creates a new webhook to receive real-time HTTP callbacks when email events occur (e.g., message received, sent). request: CreateWebhookRequest response: Webhook errors: @@ -97,6 +100,7 @@ service: method: DELETE path: /{webhook_id} display-name: Delete Webhook + docs: Removes a webhook endpoint and stops sending event notifications to that URL. path-parameters: webhook_id: WebhookId errors: diff --git a/fern/definition/websockets.yml b/fern/definition/websockets.yml index c8e06e4..06cb87b 100644 --- a/fern/definition/websockets.yml +++ b/fern/definition/websockets.yml @@ -30,6 +30,7 @@ channel: url: Websockets path: /v0 display-name: Connect + docs: Establishes a WebSocket connection for real-time bidirectional communication to receive instant email notifications and events. auth: true query-parameters: auth_token: From fe9fead37acffd0b1e7649e886954f1e9d051179 Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Wed, 3 Dec 2025 15:59:57 -0500 Subject: [PATCH 2/3] check and modify some explaination --- fern/definition/inboxes/__package__.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/definition/inboxes/__package__.yml b/fern/definition/inboxes/__package__.yml index 92ca9ee..6e12ef2 100644 --- a/fern/definition/inboxes/__package__.yml +++ b/fern/definition/inboxes/__package__.yml @@ -103,7 +103,7 @@ service: method: PATCH path: /{inbox_id} display-name: Update Inbox - docs: Updates the configuration or settings of an existing inbox such as display name or forwarding rules. + docs: Updates the configuration or settings of an existing inbox such as display name. path-parameters: inbox_id: InboxId request: UpdateInboxRequest From c9bb3ffb591d482742fed572f35fc98c9cc30a79 Mon Sep 17 00:00:00 2001 From: duharry0915 <57567430+duharry0915@users.noreply.github.com> Date: Wed, 3 Dec 2025 16:11:55 -0500 Subject: [PATCH 3/3] adding explaination for List Metrics --- fern/definition/metrics.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/definition/metrics.yml b/fern/definition/metrics.yml index 14ffc5c..c0faddf 100644 --- a/fern/definition/metrics.yml +++ b/fern/definition/metrics.yml @@ -79,6 +79,7 @@ service: method: GET path: "" display-name: List Metrics + docs: Retrieves aggregated email metrics across all inboxes in your account within a specified time range. request: name: ListMetricsRequest query-parameters: