> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/reference/agent-mail/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# AgentMail object

> Lists the contents of an agent mail object.

This page describes the `agent_mail` object, which represents mail received at a registered agent address on behalf of a company.

**`Example JSON response`**

```json title="Example JSON response"
{
  "object": "agent_mail",
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "arrived_at": "2024-01-15T09:30:00Z",
  "external_id": "mail-ext-12345",
  "sender_name": "California Secretary of State",
  "recipient_name": "Acme Corporation",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "mail_viewed": true,
  "agency_name": "California Franchise Tax Board",
  "tag_names": ["tax", "annual_report"],
  "internal_status": "processed",
  "notes": "Annual franchise tax notice",
  "document_url": "https://example.com/documents/abc123",
  "summary_payload": {
    "type": "tax_notice",
    "due_date": "2024-03-15"
  },
  "suggested_mail_tag": "tax_notice",
  "suggested_partner_name": "Acme Corporation",
  "suggested_action_request": false,
  "mailbox_name": "CA Registered Agent",
  "registration_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "CA",
  "source": {
    "type": "registration_request",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "company": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "legal_name": "Acme Corporation",
    "dba_name": "Acme Co",
    "provider_company_id": "prov-123",
    "external_id": "ext-12345",
    "parent_account_name": "Acme Holdings"
  },
  "document": null
}
```

## AgentMail attributes

| Attribute                  | Type                  | Description                                           |
| -------------------------- | --------------------- | ----------------------------------------------------- |
| `object`                   | string                | Object type identifier. Always `agent_mail`.          |
| `id`                       | string (uuid)         | Unique identifier for the mail item.                  |
| `arrived_at`               | timestamp \| null     | When the mail physically arrived.                     |
| `external_id`              | string \| null        | External identifier for the mail item in your system. |
| `sender_name`              | string \| null        | Name of the mail sender.                              |
| `recipient_name`           | string \| null        | Name of the mail recipient.                           |
| `created_at`               | timestamp             | When the mail record was created.                     |
| `updated_at`               | timestamp             | When the mail record was last updated.                |
| `mail_viewed`              | boolean               | Whether the mail has been viewed.                     |
| `agency_name`              | string \| null        | Name of the government agency if applicable.          |
| `tag_names`                | array\[string]        | List of tags associated with the mail item.           |
| `internal_status`          | string                | Internal processing status.                           |
| `notes`                    | string \| null        | Notes about the mail item.                            |
| `document_url`             | string (uri) \| null  | URL to download the scanned document.                 |
| `summary_payload`          | object \| null        | Structured summary of the mail contents.              |
| `suggested_mail_tag`       | string \| null        | AI-suggested tag for the mail.                        |
| `suggested_partner_name`   | string \| null        | AI-suggested company name match.                      |
| `suggested_action_request` | boolean               | Whether the mail suggests action is required.         |
| `mailbox_name`             | string \| null        | Name of the mailbox where mail was received.          |
| `registration_request_id`  | string (uuid) \| null | Associated registration request ID.                   |
| `state`                    | string \| null        | US state abbreviation.                                |
| `source`                   | object                | Source of the mail item.                              |
| `company`                  | object                | Company associated with this mail.                    |
| `document`                 | object \| null        | Associated document details.                          |

## Source attributes

| Attribute | Type                  | Description                                                      |
| --------- | --------------------- | ---------------------------------------------------------------- |
| `type`    | string                | Type of the source object (for example, `registration_request`). |
| `id`      | string (uuid) \| null | ID of the source object.                                         |

## Company attributes

| Attribute             | Type           | Description                                         |
| --------------------- | -------------- | --------------------------------------------------- |
| `id`                  | string (uuid)  | Unique identifier for the company.                  |
| `legal_name`          | string \| null | The company's legal name.                           |
| `dba_name`            | string \| null | The company's doing business as (DBA) name.         |
| `provider_company_id` | string \| null | Provider's company identifier.                      |
| `external_id`         | string \| null | External identifier for the company in your system. |
| `parent_account_name` | string \| null | Name of the parent account.                         |

## State values

The `state` attribute uses standard two-letter US state abbreviations (for example, `CA`, `NY`, `TX`).

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Lists the contents of an agent mail object.