agentmail 0.5.45 → 0.5.47

package/reference.md

@@ -1468,6 +1468,8 @@ Create a new agent organization with an inbox and API key. This endpoint is for
 
 A 6-digit OTP is sent to the human's email for verification.
 
+The new organization starts with 1 inbox, no custom domains, and 10 emails per day, which can be sent only to `human_email` until the organization is verified.
+
 `human_email` is optional. Without it, the inbox can receive email but cannot send to anyone until a human is attached with the attach human endpoint or, for a US-region inbox, claims it in the AgentMail Console with the API key (see [How do I claim my agent's inbox?](https://docs.agentmail.to/knowledge-base/claiming-agent-inbox)). There is also no way to recover the API key, so store it durably. Calling sign-up again without `human_email` creates a new organization, which needs a different `username`: the original username stays with the lost organization's inbox.
 
 This endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the OTP if expired.
@@ -1622,7 +1624,7 @@ await client.agent.attachHuman({
 
 Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up.
 
-On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied.
+On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and the Free plan's entitlements are applied: 3 inboxes and 100 emails per day, at first to at most 3 distinct recipients in the first hour, 5 in the first day, and 10 in the first week.
 
 The OTP expires after 24 hours and allows a maximum of 10 attempts. If the OTP expired, call the attach human endpoint with the same `human_email` to get a new one without rotating the API key. Once all 10 attempts are used, even the correct OTP is rejected, and attach human keeps returning the same OTP until it expires, so wait for it to expire before asking for a new one. An organization that signed up without a `human_email` has no OTP until a human is attached. If you run into any difficulties receiving the OTP code, you can also create an account on [console.agentmail.to](https://console.agentmail.to) using the human email address you provided to verify your account.
 
@@ -3643,9 +3645,8 @@ Gets the inbox's calendar. Every inbox has one calendar, so this works before an
 created. Its `etag` (also the `ETag` response header) is the value to send in `If-Match` to
 make an update conditional.
 
-Requires the `calendar_read` permission. Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`)
-but not yet in EU production (`api.agentmail.eu`). Organizations that have not joined
-Labs receive a `403`.
+Requires the `calendar_read` permission. Calendar is available in US production
+(`api.agentmail.to`) but not yet in EU production (`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -3723,8 +3724,8 @@ Requires the `calendar_update` permission. To make the update conditional, send
 calendar's current `etag` in `If-Match`: a stale value returns `412`. Without `If-Match` the
 update applies to the calendar as it is.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -3806,8 +3807,8 @@ use Get Agenda.
 The list is always read in the region that serves the request, so it can trail a change made
 moments earlier by a few seconds. Requires the `calendar_event_read` permission.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -3897,8 +3898,8 @@ The agenda is read in the region that serves the request, so it can trail a chan
 moments earlier by a few seconds. Pass `consistency=primary` to read your own change right
 away. Requires the `calendar_event_read` permission.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -3993,8 +3994,8 @@ charged again.
 The event's `etag` is the value to send in `If-Match` to make a later update or delete
 conditional. Requires the `calendar_event_create` permission.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -4093,8 +4094,8 @@ to read the latest state of an event or a date. A date that has already started
 reads back as it ran, even if a later change to the series no longer produces it. Requires
 the `calendar_event_read` permission.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -4198,8 +4199,8 @@ Emailing attendees counts one send per attendee against the organization, pod an
 send limits, charged before the change is saved; an over-limit request returns `429`
 `rate_limit_exceeded` and changes nothing.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -4304,8 +4305,8 @@ Emailing cancellations counts one send per attendee against the organization, po
 send limits, charged before the delete; an over-limit request returns `429`
 `rate_limit_exceeded` and deletes nothing.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -4396,8 +4397,8 @@ and `attendees`; get a date by its ID for the full object. Like other reads, the
 trail a change made moments earlier by a few seconds; pass `consistency=primary` to read
 your own change right away. Requires the `calendar_event_read` permission.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -4494,8 +4495,8 @@ A reply email counts as one send against the organization, pod and inbox send li
 charged before the response is saved; an over-limit request returns `429`
 `rate_limit_exceeded` and changes nothing.
 
-Calendar is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet
-in EU production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
+(`api.agentmail.eu`), which returns `403`.
 </dd>
 </dl>
 </dd>
@@ -5191,6 +5192,413 @@ await client.inboxes.events.list("inbox_id");
 </dl>
 
 
+</dd>
+</dl>
+</details>
+
+## Inboxes Files
+<details><summary><code>client.inboxes.files.<a href="/src/api/resources/inboxes/resources/files/client/Client.ts">create</a>(inbox_id, { ...params }) -> AgentMail.CreateFileResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Starts an upload: creates a pending file at `path` and returns an `upload` to `PUT` its bytes to. The bytes go
+straight to storage, not through the API. Then call Complete File to make the file `ready`.
+
+Retry-safe: sending the identical request again (same `path`, `size`, `sha256`, `content_type` and
+`expires_at`) returns the existing file with `200` instead of `201`: a pending one with a fresh `upload`, or
+a `ready` one without. If its bytes were uploaded but the upload was never completed, it is completed then. A
+different request at a path whose file is still pending and has no bytes replaces that file; at any other
+taken path it returns `409`.
+
+The file counts against the organization's Drive quota from creation, pending or not: 1 GiB and 10,000 files
+by default. A file that doesn't fit returns `403` with code `limit_exceeded`. Deleting a file frees its
+space within seconds. Expired files count until a create needs their space: a create that doesn't fit first
+gives back what expired files hold, a batch at a time, so retry a refusal while many expired files remain.
+
+Requires the `file_create` permission, which an unverified organization's keys don't have at any scope until
+it completes agent verification. A key without `file_read` can still create files, but gets the plain `409` at
+any taken path, even for an identical request at a file it didn't create.
+
+Agent Drive is in AgentMail Labs, available in US production (`api.agentmail.to`) but not yet in EU
+production (`api.agentmail.eu`). Organizations that have not joined Labs receive a `403`.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.files.create("reports@agentmail.to", {
+    path: "reports/q3.pdf",
+    size: 48213,
+    sha256: "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
+    contentType: "application/pdf"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request:** `AgentMail.inboxes.CreateFileRequestWrapper` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `FilesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.inboxes.files.<a href="/src/api/resources/inboxes/resources/files/client/Client.ts">complete</a>(inbox_id, file_id) -> AgentMail.File_</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Makes a pending file `ready` once its bytes are uploaded, and returns it, with its `download_url` if the key
+has `file_read`. Calling it on a file that is already `ready` returns the file.
+
+Returns `409` if the bytes haven't been uploaded yet, or if what was uploaded doesn't match the file's `size`
+and `sha256`. Returns `404` for a file that has expired or was deleted, including a pending file not
+completed within a day of its creation.
+
+Requires the `file_create` permission. Only a key with `file_read`, or the key that created the file, can
+complete it; any other key gets `404`.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.files.complete("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f");
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**file_id:** `AgentMail.FileId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `FilesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.inboxes.files.<a href="/src/api/resources/inboxes/resources/files/client/Client.ts">get</a>(inbox_id, file_id) -> AgentMail.File_</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Gets a file. A `ready` file comes with a fresh `download_url`, valid for up to an hour.
+
+A get reads the region that serves the request, so for about a second after a delete it can still return
+the deleted file. A file that has expired returns `404` at once.
+
+Requires the `file_read` permission.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.files.get("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f");
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**file_id:** `AgentMail.FileId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `FilesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.inboxes.files.<a href="/src/api/resources/inboxes/resources/files/client/Client.ts">list</a>(inbox_id, { ...params }) -> AgentMail.ListFilesResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Lists the inbox's files in path order, pending ones included, optionally only those whose path starts with
+`path_prefix`. A prefix matches characters, not whole segments: `reports/q` matches `reports/q3.pdf`. Items
+carry no download URL; get a file for one.
+
+The list is read in the region that serves the request, so a file created or deleted a moment ago may not
+show yet. Expired files never show.
+
+Requires the `file_read` permission.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.files.list("reports@agentmail.to", {
+    pathPrefix: "reports/"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request:** `AgentMail.inboxes.ListFilesRequest` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `FilesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.inboxes.files.<a href="/src/api/resources/inboxes/resources/files/client/Client.ts">delete</a>(inbox_id, file_id) -> void</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Deletes a file, pending or `ready`, and frees its path at once. Its bytes are deleted, and its space given
+back to the organization's quota, within seconds. A download URL signed before the delete keeps working
+until it expires, at most an hour. Deleting a file that is already gone returns `404`.
+
+Requires the `file_delete` permission. Only a key with `file_read`, or the key that created the file, can
+delete it; any other key gets `404`.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.files.delete("reports@agentmail.to", "6f1c2f4e-8d3b-4a5e-9c7d-1b2a3c4d5e6f");
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**file_id:** `AgentMail.FileId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `FilesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
 </dd>
 </dl>
 </details>
@@ -5867,6 +6275,94 @@ await client.inboxes.messages.createAgentArmorFeedback("inbox_id", "message_id",
 </dl>
 
 
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.inboxes.messages.<a href="/src/api/resources/inboxes/resources/messages/client/Client.ts">releaseAgentArmorMessage</a>(inbox_id, message_id, { ...params }) -> AgentMail.ReleaseAgentArmorMessageResponse</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Release a message Agent Armor held for review in hold mode: your agents are sent its `message.received`
+event, `message.security.override` is sent too, in either order, and its `agent-armor-held` label is removed.
+Only a message whose verdict is `review` and that is still held can be released; anything else answers `409`.
+Repeating a release with the same reason and the same API key returns the first release; any other repeat
+answers `409`.
+
+Requires the opt-in `agent_armor_release` permission and permission to read the message. An organization
+admin can also release from the console.
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.inboxes.messages.releaseAgentArmorMessage("inbox_id", "message_id", {
+    reason: "reason"
+});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**inbox_id:** `AgentMail.InboxId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**message_id:** `AgentMail.MessageId` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request:** `AgentMail.ReleaseAgentArmorMessageRequest` 
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `MessagesClient.RequestOptions` 
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
 </dd>
 </dl>
 </details>
@@ -8713,10 +9209,9 @@ Rolling bounce and complaint rates for the organization. At each
 `period` grid point, the bounced (or complained) messages over the
 preceding `window` divided by the messages sent over the same window,
 with the send count alongside so you can see the volume behind
-it. This is the number AgentMail's account moderation acts on: a
-warning at a 5% bounce rate and suspension at 10%, evaluated over a
-rolling 24 hours once at least 1,000 messages were sent in that
-window. Defaults to the rolling 24-hour rate sampled hourly over the
+it. AgentMail weighs bounce and complaint signals when deciding
+whether to suspend an account's sending, so keep both rates low.
+Defaults to the rolling 24-hour rate sampled hourly over the
 last day; `start` must be within the last 90 days, `window` must be a
 whole multiple of `period`, and the range plus window divided by
 `period` must not exceed 1000 buckets.
@@ -8848,7 +9343,7 @@ await client.organizations.get();
 <dl>
 <dd>
 
-Returns whether the organization is in [AgentMail Labs](https://docs.agentmail.to/calendar), which turns on features that are still in preview, such as calendar. Requires an organization-scoped API key.
+Returns whether the organization is in AgentMail Labs, which turns on features that are still in preview, such as [Agent Armor](https://docs.agentmail.to/agent-armor). Requires an organization-scoped API key.
 
 **CLI:**
 ```bash