## POST /api/v2/vps/{id}/mail-relay/charge-consent

**Update VPS mail-relay billing consent**

Enable or disable metered billing for extra VPS mail-relay sending. Send `enabled: true` only after the customer has accepted the extra-sending charge; send `enabled: false` to revoke that consent. Enabling requires the account to be eligible for pay-as-you-go billing.

### Related Endpoints

- `GET /api/v2/vps/{id}/mail-relay`: Get VPS mail-relay status
- `POST /api/v2/vps/{id}/mail-relay/quota-requests`: Create prepaid mail-relay quota invoice
- `GET /api/v2/vps/{id}`: Get VPS details

### Headers

- `Accept`: application/json
- `Authorization`: Bearer YOUR_API_KEY
- Required API scope: `write:billing`
- `Content-Type`: application/json

### Parameters

- `id` (path, string, required): Public VPS ID from `GET /api/v2/vps` `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response. Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `enabled` (boolean, required): Set to true to enable metered extra sending, or false to disable it. Example: `true`

### Request Examples

#### Enable extra sending

```bash
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
```

```json
{
  "enabled": true
}
```

#### Disable extra sending

```bash
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

```json
{
  "enabled": false
}
```

### Response Schema

- `featureKey` (string, required): Stable key for this billing consent. Example: `mail_relay_overage`
  Allowed values: mail_relay_overage
- `enabled` (boolean, required): Whether extra mail-relay sending is currently enabled. Example: `true`
- `acceptedAt` (string,null, required): Timestamp when extra-sending charges were last accepted. Example: `2026-04-27T12:00:00.000Z`
- `revokedAt` (string,null, required): Timestamp when extra-sending charges were disabled, or null while enabled. Example: `null`
- `paygEnabled` (boolean, required): Whether metered extra sending is active after the consent update. Example: `true`
- `paygEligible` (boolean, required): Whether the account is eligible for pay-as-you-go billing. Example: `true`
- `pricing` (object,null, required)

### Responses

#### 200 - Mail-relay billing consent was updated.
```json
{
  "featureKey": "mail_relay_overage",
  "enabled": true,
  "acceptedAt": "2026-04-27T12:00:00.000Z",
  "revokedAt": null,
  "paygEnabled": true,
  "paygEligible": true,
  "pricing": {
    "amount": 5,
    "currencyCode": "SEK",
    "unitEmails": 1000
  }
}
```

#### 400 - The request body did not include a boolean `enabled` value.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_charge_consent_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The charge consent request must include enabled as true or false.",
  "code": "invalid_charge_consent_request",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent",
  "errors": [
    {
      "pointer": "/enabled",
      "detail": "enabled must be a boolean.",
      "code": "invalid_type"
    }
  ]
}
```

#### 401 - Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent"
}
```

#### 403 - The account is not eligible for pay-as-you-go billing.
```json
{
  "type": "https://developer.hostup.se/errors/payg_access_required",
  "title": "PAYG access required",
  "status": 403,
  "detail": "Add a credit card to your billing account before using extra mail relay sending.",
  "code": "payg_access_required",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent",
  "extensions": {
    "reason": "no_card_on_file",
    "recovery": {
      "action": "verify_identity",
      "suggestedBody": null
    }
  }
}
```

#### 404 - The requested VPS was not found or is not accessible.
```json
{
  "type": "https://developer.hostup.se/errors/vps_not_found",
  "title": "VPS not found",
  "status": 404,
  "detail": "The requested VPS could not be found.",
  "code": "vps_not_found",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Too many requests. Retry after the limit resets.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Unexpected error while updating mail-relay billing consent.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred while updating mail relay billing consent.",
  "code": "internal_error",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/mail-relay/charge-consent"
}
```