> 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/forwarding
Content-Type: application/json

Set the addresses the organization forwards to. The list replaces the current one. An address
that is not verified is saved but receives nothing until it is verified. Needs an
organization-scoped API key in an organization that has completed agent verification.

**CLI:**
```bash
agentmail forwarding update --destinations ops@example.com --destinations archive@example.com
```

Reference: https://agentmail.to/docs/api-reference/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

### 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.

### 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/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/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/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/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/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/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/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/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()
```