API reference

Email alerts API

Read and change your email alert preferences, and the unsubscribe link every alert email carries.

Get alert preferences: GET /v1/notifications/preferences
Change alert preferences: PUT /v1/notifications/preferences
Show the unsubscribe confirmation: GET /v1/notifications/unsubscribe
Unsubscribe from one alert type: POST /v1/notifications/unsubscribe

Get alert preferences

GET /v1/notifications/preferences

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member, for their own preferences.

Parameters

Name	In	Type	Required	Description
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`NotificationPreferencesDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "alerts": [
    {
      "available": false,
      "customized": false,
      "default_enabled": false,
      "description": "A machine could not be stopped.",
      "enabled": false,
      "type": "machine_stop_failed"
    }
  ],
  "email": "ada@example.com",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}

Change alert preferences

PUT /v1/notifications/preferences

API key: Authorization: Bearer vmy_… with preset full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Any member, for their own preferences.

Parameters

Name	In	Type	Required	Description
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, UpdateNotificationPreferencesRequest)

Field	Type	Required	Description
`alerts`	`map of string`	Yes	Alert type to on (`true`) or off (`false`); unlisted types keep their current setting.

Responses

Status	Description	Body
`200`	—	`NotificationPreferencesDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X PUT "$VMYARD_API_URL/v1/notifications/preferences" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alerts": {
    "operation_failed": true,
    "auto_stop": false
  }
}'

Response 200

{
  "alerts": [
    {
      "available": false,
      "customized": false,
      "default_enabled": false,
      "description": "A machine could not be stopped.",
      "enabled": false,
      "type": "machine_stop_failed"
    }
  ],
  "email": "ada@example.com",
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "user_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
}

Show the unsubscribe confirmation

GET /v1/notifications/unsubscribe

Shows a confirmation page and changes nothing, so link scanners are harmless.

Authentication: none on this route.
Who: Anyone with an alert email's link.

Parameters

Name	In	Type	Required	Description
`token`	query	`string`	Yes	The token from the alert email's unsubscribe link.

Responses

Status	Description	Body
`200`	A confirmation page whose button POSTs the same URL; nothing changes on GET	`text/html`
`400`	Bad request.	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/notifications/unsubscribe?token=token"

Unsubscribe from one alert type

POST /v1/notifications/unsubscribe

Turns off the one alert type the token names for its member. One-click unsubscribe (RFC 8058) posts here.

Authentication: none on this route.
Who: Anyone with an alert email's link.

Parameters

Name	In	Type	Required	Description
`token`	query	`string`	Yes	The token from the alert email's unsubscribe link.

Responses

Status	Description	Body
`200`	The alert is off for that member. One-click (RFC 8058) and form posts need no session; `Accept: text/html` answers with a page.	`UnsubscribedDto`
`400`	Bad request.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/notifications/unsubscribe?token=token"

Response 200

{
  "enabled": false,
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "operation_failed"
}