> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/pods.md). # Agent Mail Pods Blocks for creating, managing, and querying pods in AgentMail. Pods provide multi-tenant isolation between customers — each pod acts as an isolated workspace containing its own inboxes, domains, threads, and drafts. Use pods when building SaaS platforms, agency tools, or AI agent fleets serving multiple customers. ## Agent Mail Create Pod ### What it is Create a new pod for multi-tenant customer isolation. Use client\_id to map to your internal tenant IDs. ### How it works Calls the AgentMail API to provision a new pod, passing an optional `client_id` parameter. When a `client_id` is provided, AgentMail maps it to the pod so you can later reference the pod using your own internal tenant identifier instead of the AgentMail-assigned `pod_id`. The block returns the newly created `pod_id` along with the complete pod object containing all metadata. Any API errors propagate directly to the global error handler. ### Inputs | Input | Description | Type | Required | | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | ---- | -------- | | client\_id | Your internal tenant/customer ID for idempotent mapping. Lets you access the pod by your own ID instead of AgentMail's pod\_id. | str | No | ### Outputs | Output | Description | Type | | ------- | ------------------------------------- | --------------- | | error | Error message if the operation failed | str | | pod\_id | Unique identifier of the created pod | str | | result | Complete pod object with all metadata | Dict\[str, Any] | ### Possible use case * **SaaS Customer Onboarding** — Automatically provision an isolated email workspace when a new customer signs up for your platform. * **AI Agent Fleet Management** — Create a dedicated pod for each AI agent so its email activity is fully isolated from other agents. * **White-Label Email Service** — Spin up tenant-scoped pods mapped to your internal customer IDs to power a branded email product. *** ## Agent Mail Create Pod Inbox ### What it is Create a new email inbox within a pod. The inbox is scoped to the customer workspace. ### How it works Calls the AgentMail API to create a new inbox scoped to the specified pod. You can optionally provide a `username`, `domain`, and `display_name` to customize the email address and sender identity. If omitted, the username is auto-generated and the domain defaults to `agentmail.to`. The block returns the `inbox_id`, the full `email_address`, and the complete inbox metadata object. The inbox is fully isolated within the pod, meaning it only appears in that pod's inbox listings and its threads stay separate from other pods. ### Inputs | Input | Description | Type | Required | | ------------- | ------------------------------------------------------------------------------- | ---- | -------- | | pod\_id | Pod ID to create the inbox in | str | Yes | | username | Local part of the email address (e.g. 'support'). Leave empty to auto-generate. | str | No | | domain | Email domain (e.g. 'mydomain.com'). Defaults to agentmail.to if empty. | str | No | | display\_name | Friendly name shown in the 'From' field (e.g. 'Customer Support') | str | No | ### Outputs | Output | Description | Type | | -------------- | --------------------------------------- | --------------- | | error | Error message if the operation failed | str | | inbox\_id | Unique identifier of the created inbox | str | | email\_address | Full email address of the inbox | str | | result | Complete inbox object with all metadata | Dict\[str, Any] | ### Possible use case * **Per-Customer Support Addresses** — Create a `support@clientdomain.com` inbox inside each customer's pod so inbound support emails are automatically routed to the right tenant. * **Branded Outbound Campaigns** — Provision inboxes with custom display names and domains for each customer's marketing agent to send branded emails. * **Multi-Department Agent Setup** — Create separate inboxes (sales, billing, support) within a single customer pod so different AI agents handle different functions. *** ## Agent Mail Delete Pod ### What it is Permanently delete a pod. All inboxes and domains must be removed first. ### How it works Calls the AgentMail API to permanently delete the specified pod. The API enforces a precondition: all inboxes and custom domains must be removed from the pod before deletion is allowed. If any remain, the API returns an error that propagates to the global error handler. On success the block returns `success=True`. This operation is irreversible -- the pod and its associated `client_id` mapping are permanently removed. ### Inputs | Input | Description | Type | Required | | ------- | -------------------------------------------------------------- | ---- | -------- | | pod\_id | Pod ID to permanently delete (must have no inboxes or domains) | str | Yes | ### Outputs | Output | Description | Type | | ------- | ---------------------------------------- | ---- | | error | Error message if the operation failed | str | | success | True if the pod was successfully deleted | bool | ### Possible use case * **Customer Offboarding** — Automatically delete a customer's pod after they cancel their subscription and all their inboxes have been cleaned up. * **Development Environment Cleanup** — Tear down temporary pods created during testing or staging so they do not accumulate over time. * **Compliance Data Removal** — Permanently remove a tenant's email workspace as part of a GDPR or data-deletion request workflow. *** ## Agent Mail Get Pod ### What it is Retrieve details of an existing pod including its client\_id mapping and metadata. ### How it works Calls the AgentMail API with the given `pod_id` to fetch the full pod record. The returned object includes the pod's `client_id` mapping, creation timestamp, and any other metadata stored on the pod. The block outputs both the `pod_id` and the complete result dictionary. If the pod does not exist, the API error propagates directly to the global error handler. ### Inputs | Input | Description | Type | Required | | ------- | ------------------ | ---- | -------- | | pod\_id | Pod ID to retrieve | str | Yes | ### Outputs | Output | Description | Type | | ------- | ------------------------------------- | --------------- | | error | Error message if the operation failed | str | | pod\_id | Unique identifier of the pod | str | | result | Complete pod object with all metadata | Dict\[str, Any] | ### Possible use case * **Tenant Dashboard Display** — Fetch pod details to show a customer's workspace status, creation date, and associated client ID on an admin dashboard. * **Pre-Action Validation** — Retrieve pod metadata before performing operations like inbox creation to confirm the pod exists and is correctly mapped. * **Audit Logging** — Pull pod details as part of an automated audit trail that records which tenant workspace was accessed and when. *** ## Agent Mail List Pod Drafts ### What it is List all drafts across all inboxes within a pod. View pending emails for a customer. ### How it works Calls the AgentMail API to retrieve drafts across all inboxes within the specified pod. Optional `limit` and `page_token` parameters control pagination. Only non-empty parameters are sent to the API. The block returns the list of draft objects, a `count` of drafts in the current page, and a `next_page_token` for fetching subsequent pages. This provides a pod-wide view of unsent emails without needing to query each inbox individually. ### Inputs | Input | Description | Type | Required | | ----------- | ----------------------------------------------------- | ---- | -------- | | pod\_id | Pod ID to list drafts from | str | Yes | | limit | Maximum number of drafts to return per page (1-100) | int | No | | page\_token | Token from a previous response to fetch the next page | str | No | ### Outputs | Output | Description | Type | | ----------------- | -------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | drafts | List of draft objects from all inboxes in this pod | List\[Dict\[str, Any]] | | count | Number of drafts returned | int | | next\_page\_token | Token for the next page. Empty if no more results. | str | ### Possible use case * **Draft Review Queue** — Surface all pending drafts across a customer's inboxes so a human reviewer can approve or discard them before sending. * **Stuck Draft Detection** — Periodically list pod drafts to find emails that have been sitting unsent for too long and alert the responsible agent or operator. * **Customer Activity Summary** — Include draft counts in a tenant dashboard to show how many outbound emails are queued and awaiting dispatch. *** ## Agent Mail List Pod Inboxes ### What it is List all inboxes within a pod. View email accounts scoped to a specific customer. ### How it works Calls the AgentMail API to list all inboxes belonging to the specified pod. Optional `limit` and `page_token` parameters enable paginated retrieval. Only non-empty parameters are included in the API call. The block returns the list of inbox objects, a `count` of inboxes in the current page, and a `next_page_token` for fetching additional pages. Each inbox object includes its ID, email address, display name, and other metadata. ### Inputs | Input | Description | Type | Required | | ----------- | ----------------------------------------------------- | ---- | -------- | | pod\_id | Pod ID to list inboxes from | str | Yes | | limit | Maximum number of inboxes to return per page (1-100) | int | No | | page\_token | Token from a previous response to fetch the next page | str | No | ### Outputs | Output | Description | Type | | ----------------- | -------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | inboxes | List of inbox objects within this pod | List\[Dict\[str, Any]] | | count | Number of inboxes returned | int | | next\_page\_token | Token for the next page. Empty if no more results. | str | ### Possible use case * **Customer Inbox Inventory** — Display all email addresses belonging to a tenant on their settings page so they can manage or remove unused inboxes. * **Pre-Deletion Validation** — List a pod's inboxes before attempting to delete the pod, ensuring all inboxes have been removed as required by the API. * **Multi-Inbox Routing Overview** — Show operators which inboxes exist in a customer's pod so they can configure routing rules for each address. *** ## Agent Mail List Pod Threads ### What it is List all conversation threads across all inboxes within a pod. View all email activity for a customer. ### How it works Calls the AgentMail API to retrieve conversation threads across all inboxes in the specified pod. Supports optional `limit`, `page_token`, and `labels` parameters. When `labels` are provided, only threads matching all specified labels are returned. The block returns the list of thread objects, a `count` for the current page, and a `next_page_token` for pagination. This gives a unified, cross-inbox view of all email conversations within a customer's workspace. ### Inputs | Input | Description | Type | Required | | ----------- | ----------------------------------------------------- | ---------- | -------- | | pod\_id | Pod ID to list threads from | str | Yes | | limit | Maximum number of threads to return per page (1-100) | int | No | | page\_token | Token from a previous response to fetch the next page | str | No | | labels | Only return threads matching ALL of these labels | List\[str] | No | ### Outputs | Output | Description | Type | | ----------------- | --------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | threads | List of thread objects from all inboxes in this pod | List\[Dict\[str, Any]] | | count | Number of threads returned | int | | next\_page\_token | Token for the next page. Empty if no more results. | str | ### Possible use case * **Unified Customer Inbox View** — Aggregate all email threads from every inbox in a customer's pod into a single activity feed for support agents or dashboards. * **Label-Based Ticket Triage** — Filter pod threads by labels like "urgent" or "billing" to route conversations to the appropriate AI agent or human team. * **Conversation Volume Monitoring** — Periodically list pod threads to track email volume per tenant and trigger alerts when activity spikes or drops. *** ## Agent Mail List Pods ### What it is List all tenant pods in your organization. See all customer workspaces at a glance. ### How it works Calls the AgentMail API to list all pods in your organization. Optional `limit` and `page_token` parameters control pagination. Only non-empty parameters are included in the request. The block returns a list of pod objects (each containing `pod_id`, `client_id`, creation time, and other metadata), a `count` for the current page, and a `next_page_token` for retrieving additional pages. ### Inputs | Input | Description | Type | Required | | ----------- | ----------------------------------------------------- | ---- | -------- | | limit | Maximum number of pods to return per page (1-100) | int | No | | page\_token | Token from a previous response to fetch the next page | str | No | ### Outputs | Output | Description | Type | | ----------------- | ----------------------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | pods | List of pod objects with pod\_id, client\_id, creation time, etc. | List\[Dict\[str, Any]] | | count | Number of pods returned | int | | next\_page\_token | Token for the next page. Empty if no more results. | str | ### Possible use case * **Admin Tenant Overview** — Display all customer pods on an internal admin dashboard so operators can monitor workspace count and health at a glance. * **Automated Tenant Reconciliation** — Periodically list all pods and compare against your internal customer database to detect orphaned or missing workspaces. * **Usage Reporting** — Enumerate all pods to generate per-tenant usage reports or billing summaries based on workspace activity. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://agpt.co/docs/integrations/block-integrations/pods.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.