> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://www.agentmail.to/docs/llms.txt.

# Update Forwarding

PUT https://api.agentmail.to/v0/inboxes/{inbox_id}/forwarding
Content-Type: application/json

Set the addresses this inbox forwards to. The list replaces the inbox's current one and any pod
or organization list for this inbox; lists are never combined. Send an empty list to stop this
inbox forwarding even when its pod or the organization forwards. An address that is not
verified is saved but receives nothing until it is verified.

**CLI:**

```bash
agentmail inboxes forwarding update --inbox-id <inbox_id> --destinations ops@example.com
```

Reference: https://agentmail.to/docs/api-reference/inboxes/forwarding/update

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.agentmail.to` (prod, default)
- `https://x402.api.agentmail.to` (prod-x402)
- `https://mpp.api.agentmail.to` (prod-mpp)
- `https://api.agentmail.eu` (eu-prod)

## Request

### Path parameters

- `inbox_id` (string, required) — The ID of the inbox.

### Body (application/json)

This endpoint expects an UpdateForwardingRequest.

- `destinations` (list of string, required) — The full list of addresses this level forwards to. It replaces the level's current list. At most 5, with no repeats. Send an empty list to turn forwarding off at this level, even when a level above forwards.

## Response

### 200

- `destinations` (list of string, required) — The list now set on this level. It does not say which addresses are verified; Get Forwarding does.

## Errors

### 400 Validation Error

- `name` (string, required) — Name of error.
- `errors` (any, required) — Validation errors. Each entry has a path and a message identifying the invalid field.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `message` (string, optional) — Error message.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 404 Not Found Error

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

### 403 Forwarding Forbidden Error

`code` says why. `missing_permission` when the API key lacks the permission the endpoint needs, including an inbox- or pod-scoped key on the organization's forwarding, an inbox-scoped key on Start or Confirm Verification, and any change other than an inbox's forwarding in an organization that hasn't completed agent verification. `account_suspended` when the organization is suspended (Start Verification). For Confirm Verification, `forbidden` when no code is outstanding for the address (none was sent, it was used, or it expired) or the code is wrong, with `message` saying how many attempts remain, and `limit_exceeded` when the code has used all its attempts. When no code is outstanding or no attempts remain, call Start Verification for a new code.

- `name` (string, required) — Name of error.
- `message` (string, required) — Error message.
- `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
- `fix` (string, optional) — The concrete next action that resolves the error.
- `docs` (string, optional) — Link to the error reference entry for this code.

## Examples

**Request**

```json
{
  "destinations": [
    "destinations",
    "destinations"
  ]
}
```

**Response**

```json
{
  "destinations": [
    "destinations",
    "destinations"
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.agentmail.to/v0/inboxes/inbox_id/forwarding"

payload = { "destinations": ["destinations", "destinations"] }
headers = {
    "Authorization": "Bearer <api_key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.agentmail.to/v0/inboxes/inbox_id/forwarding';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <api_key>', 'Content-Type': 'application/json'},
  body: '{"destinations":["destinations","destinations"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agentmail.to/v0/inboxes/inbox_id/forwarding"

	payload := strings.NewReader("{\n  \"destinations\": [\n    \"destinations\",\n    \"destinations\"\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <api_key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.agentmail.to/v0/inboxes/inbox_id/forwarding")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destinations\": [\n    \"destinations\",\n    \"destinations\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.agentmail.to/v0/inboxes/inbox_id/forwarding")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destinations\": [\n    \"destinations\",\n    \"destinations\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.agentmail.to/v0/inboxes/inbox_id/forwarding', [
  'body' => '{
  "destinations": [
    "destinations",
    "destinations"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_id/forwarding");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"destinations\": [\n    \"destinations\",\n    \"destinations\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = ["destinations": ["destinations", "destinations"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes/inbox_id/forwarding")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```