SFTPGo Octri Preview
POST/eventactions

Create an event action

Creates an event action that can be referenced by event rules. Supply name and type, then configure the matching sub-object in options; sub-objects that do not match type are zeroed on save. Use confidential_data=1 to include confidential values in the response when you have the required permission.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 6 body fields
confidential_dataintegeroptional
Set to 1 to include confidential data, including secret keys and additional secret data, in the response. This setting is ignored if you do not have the required permission.

Event action definition. Provide the required name and type, and configure the matching action-specific sub-object in options.

descriptionstringoptional
Optional description of what the action does.
idintegeroptional
Read-only action identifier populated by the server; ignored on write.
namestringrequired
Unique action name. Must be unique across all event actions.
optionsobjectoptional
Tagged union of action-specific sub-configurations. **Only the sub-object whose key matches the parent action's `type` is read**; the others are zeroed on save. Mapping (see `EventActionTypes`): type 1 → `http_config`, type 2 → `cmd_config`, type 3 → `email_config`, type 8 → `retention_config`, type 9 → `fs_config`, type 11 → `pwd_expiration_config`, type 13 → `idp_config`, type 14 → `user_inactivity_config`, type 16 → `imap_config`, type 17 → `icap_config`, type 18 → `share_expiration_config`, type 19 → `event_report_config`. Types 4, 5, 6, 7, 12, 15 have no sub-configuration.
rulesarray<string>optional
Names of event rules referencing this action. Populated on read; ignored on write.
typeintegerrequired
Supported event action types. The value selects which sub-config inside `BaseEventActionOptions` is active; all other sub-configs are zeroed on save. Types marked **Premium** require a Premium-tier license. * `1` - HTTP → `options.http_config` (templated: `endpoint`, `body`, `headers[].value`, `query_parameters[].value`, `parts[].filepath`, `parts[].body`, `parts[].headers[].value`) * `2` - Command → `options.cmd_config` (templated: `args[]`, `env_vars[].value`). The binary must be allow-listed via `SFTPGO_HOOK__ENABLED_ACTION_COMMANDS`. * `3` - Email → `options.email_config` (templated: `recipients[]`, `bcc[]`, `subject`, `body`, `attachments[]`) * `4` - Backup (no sub-config) * `5` - User quota reset (no sub-config) * `6` - Folder quota reset (no sub-config) * `7` - Transfer quota reset (no sub-config) * `8` - Data retention check → `options.retention_config`. Populates `{{.RetentionChecks}}` for downstream actions in the same rule. * `9` - Filesystem → `options.fs_config`. The nested `fs_config.type` picks the sub-action (see `FilesystemActionTypes`). * `11` - Password expiration check → `options.pwd_expiration_config` * `12` - User expiration check (no sub-config) * `13` - Identity Provider account check → `options.idp_config` (**Premium**; templated: `template_user`, `template_admin` — each is a Go template that renders a full User/Admin JSON payload. Intended for just-in-time provisioning after OIDC login.) * `14` - User inactivity check → `options.user_inactivity_config` * `15` - Rotate log file (no sub-config) * `16` - IMAP → `options.imap_config` (**Premium**; templated: `email[]`, `subject`, `body`, `attachments[]`, `target_folder`) * `17` - ICAP → `options.icap_config` (**Premium**; templated: `paths[]`) * `18` - Share expiration check → `options.share_expiration_config`. Populates `{{.ShareExpirationChecks}}` for downstream actions. * `19` - Event report → `options.event_report_config` (**Premium**). Populates `{{.EventReports}}` for downstream email/HTTP actions. See the **[sftpgo](https://github.com/sftpgo/sftpgo-skill)** reference skill for the full template context, registered functions, and worked examples.
Allowed:123456789111213

6 status codes
201Returns the created event action, including its identifier, name, type, and action-specific options.
descriptionstringoptional
Optional description of what the action does.
idintegeroptional
namestringrequired
Unique action name. Must be unique across all event actions.
optionsobjectoptional
Tagged union of action-specific sub-configurations. **Only the sub-object whose key matches the parent action's `type` is read**; the others are zeroed on save. Mapping (see `EventActionTypes`): type 1 → `http_config`, type 2 → `cmd_config`, type 3 → `email_config`, type 8 → `retention_config`, type 9 → `fs_config`, type 11 → `pwd_expiration_config`, type 13 → `idp_config`, type 14 → `user_inactivity_config`, type 16 → `imap_config`, type 17 → `icap_config`, type 18 → `share_expiration_config`, type 19 → `event_report_config`. Types 4, 5, 6, 7, 12, 15 have no sub-configuration.
rulesarray<string>optional
Names of event rules referencing this action. Populated on read; ignored on write.
typeintegerrequired
Supported event action types. The value selects which sub-config inside `BaseEventActionOptions` is active; all other sub-configs are zeroed on save. Types marked **Premium** require a Premium-tier license. * `1` - HTTP → `options.http_config` (templated: `endpoint`, `body`, `headers[].value`, `query_parameters[].value`, `parts[].filepath`, `parts[].body`, `parts[].headers[].value`) * `2` - Command → `options.cmd_config` (templated: `args[]`, `env_vars[].value`). The binary must be allow-listed via `SFTPGO_HOOK__ENABLED_ACTION_COMMANDS`. * `3` - Email → `options.email_config` (templated: `recipients[]`, `bcc[]`, `subject`, `body`, `attachments[]`) * `4` - Backup (no sub-config) * `5` - User quota reset (no sub-config) * `6` - Folder quota reset (no sub-config) * `7` - Transfer quota reset (no sub-config) * `8` - Data retention check → `options.retention_config`. Populates `{{.RetentionChecks}}` for downstream actions in the same rule. * `9` - Filesystem → `options.fs_config`. The nested `fs_config.type` picks the sub-action (see `FilesystemActionTypes`). * `11` - Password expiration check → `options.pwd_expiration_config` * `12` - User expiration check (no sub-config) * `13` - Identity Provider account check → `options.idp_config` (**Premium**; templated: `template_user`, `template_admin` — each is a Go template that renders a full User/Admin JSON payload. Intended for just-in-time provisioning after OIDC login.) * `14` - User inactivity check → `options.user_inactivity_config` * `15` - Rotate log file (no sub-config) * `16` - IMAP → `options.imap_config` (**Premium**; templated: `email[]`, `subject`, `body`, `attachments[]`, `target_folder`) * `17` - ICAP → `options.icap_config` (**Premium**; templated: `paths[]`) * `18` - Share expiration check → `options.share_expiration_config`. Populates `{{.ShareExpirationChecks}}` for downstream actions. * `19` - Event report → `options.event_report_config` (**Premium**). Populates `{{.EventReports}}` for downstream email/HTTP actions. See the **[sftpgo](https://github.com/sftpgo/sftpgo-skill)** reference skill for the full template context, registered functions, and worked examples.
Allowed:123456789111213
400Returned when the request is invalid, including when required fields are missing or values fail validation.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when the request is unauthenticated.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the caller does not have permission to create the event action.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when an internal server error occurs.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
defaultUnexpected Error
errorstringoptional
error description if any
messagestringoptional
message, can be empty

Error handling

A 400 indicates an invalid request, a 401 indicates missing or invalid authentication, a 403 indicates insufficient permission, and a 500 indicates an internal server error. name and type are required, and name must be unique across event actions. type must be one of 1–9, 11, 12, or 13; configure only the options sub-object matching that type.