Configure mail and file storage

Configure mail and file storage as a superuser before enabling workflows that send email or accept uploaded files. Use synthetic values while reviewing the form; save provider credentials only in the protected settings workflow.

Before you begin

Confirm the SMTP host, port, sender identity, TLS requirement, and authentication method with your mail provider. For S3-compatible storage, obtain the bucket, region, endpoint, access key, and secret from the storage provider. Do not paste secrets into tickets, screenshots, or source control.

Configure SMTP delivery

1

Open Mail settings

Open Settings, then select Mail settings. The mail administration screen contains the SMTP delivery configuration.

2

Enter the SMTP connection

Enable SMTP and enter the provider host and port. Set TLS according to the provider requirement; when TLS is false, PocketBase sends StartTLS and leaves the server to decide whether to upgrade. Use PLAIN or LOGIN for Auth method when required; an empty method defaults to PLAIN.

Use a shape such as smtp.example.test, port 587, and sender address noreply@example.test while validating the form. The localName value is optional and defaults to localhost; some relays require a real domain name for the initial EHLO/HELO exchange.

3

Send a test email and verify delivery

Save the settings, then use the available test-email action with a mailbox you control and the appropriate template, such as verification. Confirm receipt and inspect the application logs if the provider rejects the connection.

Choose file storage

1

Open Files storage

Return to Settings and select Files storage. The file storage administration screen exposes local and S3-compatible storage options.

2

Keep local storage or enter S3 settings

Local storage writes uploaded files under pb_data/storage and is the recommended option for many deployments because it is fast to work with and straightforward to back up. If you need external object storage, enable S3 and enter the bucket, region, public endpoint, access key, and secret. Enable Force path style only when the provider requires path-style addressing.

3

Test the connection before switching traffic

Use the storage connection test after entering S3 settings. A successful test confirms that PocketBase can initialize the selected filesystem; it does not replace a full upload and download check in a staging environment.

Protect uploaded files

Files are public by default when a caller knows the full URL. Mark a file field Protected when the file contains sensitive material. Protected-file requests require a short-lived file token and must satisfy the collection's View API rule. Keep the token out of logs and client-visible permanent URLs.

Troubleshooting

The SMTP provider rejects the connection

Check the host, port, TLS mode, and authentication method. If the provider requires a valid EHLO/HELO domain, set localName to that domain instead of relying on localhost, then send another test email.

S3 initialization fails

Verify the bucket, region, endpoint, access key, and secret as a set. Check whether the provider requires Force path style, then rerun the connection test without exposing the secret in a log or screenshot.

A protected file returns an authorization error

Confirm that the request includes a fresh file token and that the record's View API rule permits the requesting user. The token alone does not bypass the collection rule.

Next steps

Review Files, protected files, and storage, then configure Backups and restore so the selected storage is included in your recovery plan.