# My mail

Source: https://opvs.ai/docs/api/my-mail

## `POST` /api/v1/me/mail/files

**Upload My Mail File**

Validate and privately store one file owned by the caller's mailbox.

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/me/mail/files' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "file": "string"
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/me/mail/files",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"file": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/files", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"file": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"file": "string"}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/me/mail/files", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `201` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/me/mail/files/{file_id}

**Read My Mail File Metadata**

**Parameters**

- `file_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail/files/{file_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail/files/{file_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/files/{file_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail/files/{file_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/me/mail/files/{file_id}/content

**Read My Mail File Content**

**Parameters**

- `file_id` (path, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail/files/{file_id}/content' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail/files/{file_id}/content",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/files/{file_id}/content", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail/files/{file_id}/content", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/me/mail/address/availability

**Check My Address Availability**

Check whether a new ``opvs.run`` local part can be claimed.

**Parameters**

- `name` (query, string, required)

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail/address/availability' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail/address/availability",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/address/availability", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail/address/availability", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `PUT` /api/v1/me/mail/address

**Change My Address**

Change my OPVS address; the old address forwards for 30 days.

**Request body**

```bash
curl -X PUT 'https://app.opvs.ai/api/v1/me/mail/address' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'
```

```python
import httpx

resp = httpx.put(
    "https://app.opvs.ai/api/v1/me/mail/address",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"name": "string"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/address", {
  method: "PUT",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "string"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"name": "string"}`)
	req, _ := http.NewRequest("PUT", "https://app.opvs.ai/api/v1/me/mail/address", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/me/mail/contacts

**List My Contacts**

People, agents, dev agents and roles of this brand I can write to.

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail/contacts' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail/contacts",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/contacts", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail/contacts", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response

## `GET` /api/v1/me/mail

**List My Mail**

**Parameters**

- `status` (query, any, optional)
- `limit` (query, integer, optional)
- `q` (query, any, optional) — Mailbox search. Same operators as the dashboard search box.
- `cursor` (query, any, optional) — Next page of a mailbox search. Ignored when q is empty.
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `GET` /api/v1/me/mail/threads/{thread_id}

**Read My Mail Thread**

**Parameters**

- `thread_id` (path, string, required)
- `format` (query, any, optional) — Response format: yaml or md

```bash
curl -X GET 'https://app.opvs.ai/api/v1/me/mail/threads/{thread_id}' \
  -H 'Authorization: Bearer <token>'
```

```python
import httpx

resp = httpx.get(
    "https://app.opvs.ai/api/v1/me/mail/threads/{thread_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/threads/{thread_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://app.opvs.ai/api/v1/me/mail/threads/{thread_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `PATCH` /api/v1/me/mail/messages/{message_id}/flags

**Update My Mail Flags**

Set private UI flags without changing or contacting the wire protocol.

**Parameters**

- `message_id` (path, string, required)

**Request body**

```bash
curl -X PATCH 'https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/flags' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "unread": true,
  "labels": [
    "string"
  ]
}'
```

```python
import httpx

resp = httpx.patch(
    "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/flags",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"unread": true, "labels": ["string"]},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/flags", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"unread": true, "labels": ["string"]})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"unread": true, "labels": ["string"]}`)
	req, _ := http.NewRequest("PATCH", "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/flags", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `PATCH` /api/v1/me/mail/messages/{message_id}/status

**Update My Mail Status**

**Parameters**

- `message_id` (path, string, required)

**Request body**

```bash
curl -X PATCH 'https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/status' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "seen"
}'
```

```python
import httpx

resp = httpx.patch(
    "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/status",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"status": "seen"},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/status", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "seen"})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"status": "seen"}`)
	req, _ := http.NewRequest("PATCH", "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/status", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/me/mail/send

**Send My Mail**

**Parameters**

- `Idempotency-Key` (header, any, optional)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/me/mail/send' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "string",
  "body": "string",
  "type": ".",
  "priority": "normal",
  "tags": [
    "string"
  ],
  "details": {},
  "file_ids": [
    "string"
  ]
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/me/mail/send",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"to": "string", "body": "string", "type": ".", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/send", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"to": "string", "body": "string", "type": ".", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"to": "string", "body": "string", "type": ".", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/me/mail/send", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## `POST` /api/v1/me/mail/messages/{message_id}/reply

**Reply To My Mail**

**Parameters**

- `message_id` (path, string, required)

**Request body**

```bash
curl -X POST 'https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/reply' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "body": "string",
  "type": "?",
  "priority": "normal",
  "tags": [
    "string"
  ],
  "details": {},
  "file_ids": [
    "string"
  ]
}'
```

```python
import httpx

resp = httpx.post(
    "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/reply",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"body": "string", "type": "?", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]},
)
resp.raise_for_status()
print(resp.json())
```

```javascript
const resp = await fetch("https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/reply", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"body": "string", "type": "?", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]})
});
const data = await resp.json();
console.log(data);
```

```go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"body": "string", "type": "?", "priority": "normal", "tags": ["string"], "details": {}, "file_ids": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/reply", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}
```

**Responses**

- `200` — Successful Response
- `422` — Validation Error

## Upload My Mail File

`POST https://app.opvs.ai/api/v1/me/mail/files`

Validate and privately store one file owned by the caller's mailbox.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read My Mail File Metadata

`GET https://app.opvs.ai/api/v1/me/mail/files/{file_id}`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read My Mail File Content

`GET https://app.opvs.ai/api/v1/me/mail/files/{file_id}/content`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Check My Address Availability

`GET https://app.opvs.ai/api/v1/me/mail/address/availability`

Check whether a new ``opvs.run`` local part can be claimed.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Change My Address

`PUT https://app.opvs.ai/api/v1/me/mail/address`

Change my OPVS address; the old address forwards for 30 days.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## List My Contacts

`GET https://app.opvs.ai/api/v1/me/mail/contacts`

People, agents, dev agents and roles of this brand I can write to.

## List My Mail

`GET https://app.opvs.ai/api/v1/me/mail`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Read My Mail Thread

`GET https://app.opvs.ai/api/v1/me/mail/threads/{thread_id}`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Update My Mail Flags

`PATCH https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/flags`

Set private UI flags without changing or contacting the wire protocol.

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Update My Mail Status

`PATCH https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/status`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Send My Mail

`POST https://app.opvs.ai/api/v1/me/mail/send`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |

## Reply To My Mail

`POST https://app.opvs.ai/api/v1/me/mail/messages/{message_id}/reply`

| Code | When | What to do |
| --- | --- | --- |
| 422 | Validation Error |  |