Skip to content

Settings

Instance settings control how Plenary sends email, sends SMS sign-in codes, stores media, and signs people in through an identity provider. An administrator sets them once per installation in the console, under Admin Settings → Global Settings. They apply to every site. Site-level options such as locales and timezone are on each site; see Sites.

On Plenary Cloud, the platform manages email, SMS, and storage for you, and the Global Settings page is not shown; single sign-on stays yours to configure. See Settings on Plenary Cloud.

A self-hosted instance keeps configuration in two places:

  • plenary.yaml, the server’s configuration file, holds anything the server needs before it can reach its database, and anything that describes the host: ports, the public URL, the database URL, secret key files, filesystem paths, logging, and tuning.
  • The database, edited in the console, holds what the installation does: which email provider to use, which SMS provider, and where media goes.
Setting Where Edited by
Server port, public_url, trusted proxies plenary.yaml (server) Whoever deploys the server
MongoDB URL plenary.yaml (mongodb) Deployer
Encryption and JWT signing key files plenary.yaml (secrets) Deployer
Token lifetimes plenary.yaml (auth.jwt) Deployer
Local media directory and temp directory plenary.yaml (storage.local_data_dir, storage.temp_dir) Deployer
Default locale and timezone for new sites plenary.yaml (locale) Deployer
Logging, webhook delivery tuning, schedule sweep interval plenary.yaml (logging, webhooks, content) Deployer
License file path plenary.yaml (license.file) or PLENARY_LICENSE Deployer; see Licensing
Email provider Database Admin, in Email Sending
SMS provider Database Admin, in SMS Sending
Media storage backend Database Admin, in File Storage
Identity provider for single sign-on Database, or seeded once from plenary.yaml (single_sign_on) Admin, in Single Sign-On; see Single sign-on
Sites, locales, timezones Database Admin, in Site Management; see Sites

The Global Settings endpoints are for super users only. No role or grant reaches them.

Provider API keys, SMTP passwords, and AWS secret access keys are encrypted before Plenary stores them. They are write-only:

  • No response ever returns a stored secret. The API returns *_configured: true and a *_hint with the last four characters (for secrets of twelve characters or more), so you can tell which credential is stored.
  • Leaving a secret field out of a save keeps the stored value. Sending an empty string clears it.
  • The console shows “A value ending … is stored. Leave this blank to keep it.”

The encryption key comes from the file named by secrets.encryption_key_file in plenary.yaml. Back up that file with your database. Without it, every stored credential is unreadable and must be entered again.

Plenary sends email for user invitations, password resets, email address confirmations, email sign-in codes, and form notifications. Until a provider is configured and Send email is on, none of these are sent.

  1. Go to Admin Settings → Global Settings and select Email Sending.

  2. Choose a provider:

    Provider Console label Needs
    ses AWS SES Access key ID, secret access key, region, optional configuration set
    sendgrid SendGrid An API key with Mail Send permission
    mandrill Mailchimp (Mandrill) A Mandrill transactional API key
    smtp Custom SMTP Host, port, username, password, encryption (STARTTLS, TLS, or none)
  3. Fill in the Sender identity: From address, From name, and optionally Reply-to address. The from address’s domain must be verified with your provider.

  4. Click Save changes.

  5. Click Send test email. The test goes to your own address and uses the saved settings, so save first.

Plenary builds the provider when you save. If the settings cannot produce a working provider, the save is refused with 422 email_settings_invalid and a reason, so you find out while you can still see what you typed.

Each provider’s settings are kept when you switch to another one, so switching back loses nothing. A development installation also offers a Development provider that writes mail to the server log instead of sending it.

The email templates (invitation, password reset, sign-in code, email confirmation, form notification) are built into Plenary and are not edited in the console.

Below the provider list, the panel shows the last 24 hours of sends: status, template, provider, a masked destination, and any failure message. It never shows message bodies or full addresses.

Plenary uses SMS for one thing: sign-in codes for users with two-factor sign-in, sent to their verified phone number. Plenary always generates the code; the provider only delivers it inside a message the provider composes. Neither provider sends arbitrary text.

  1. Go to Admin Settings → Global Settings and select SMS Sending.

  2. Choose a provider:

    Twilio Verify (twilio)

    • Account SID and Auth token.
    • Verify service SID, which starts with VA.
    • In the Twilio console, enable Custom Verification Code on that Verify service. Twilio refuses Plenary’s codes until you do. There is no from number to configure.

    AWS End User Messaging Notify (aws)

    • Access key ID, Secret access key, and Region.
    • Notify configuration ID, which starts with nc-. The configuration owns the sender identity.
    • Optional Template ID for a pre-approved code-verification template. Leave it blank to use the configuration’s default.
    • Optional Configuration set.
  3. Click Save changes.

  4. Enter a Test recipient and click Send test message. The test sends a real code, which you can ignore.

Choose SMS Disabled to stop all text messages. The provider settings are kept for when you turn SMS back on.

While SMS is disabled, the console hides the SMS phone field and the two-factor switch on users, and users with two-factor sign-in receive their codes by email, if their email address is verified. A two-factor user with no usable destination cannot sign in. See Users & Permissions.

File Storage decides where the Media Library keeps uploaded files and their generated variants.

Backend Console label Configured where
local Local disk Nothing to set here. Files go under storage.local_data_dir in plenary.yaml, normally a mounted volume.
s3 AWS S3 Access key ID, Secret access key, Region, Bucket, optional Key prefix, and Public base URL

Public base URL is where public objects are served from: the bucket’s own URL or a CDN in front of it.

Media URLs do not depend on the backend. Every file is addressed as /media/{media_id}/{filename} on your instance, and Plenary redirects to the bucket when the file is stored there. URLs already inside published content keep working when you change backends.

Switching backends affects new uploads only. Files already stored stay where they are and are still served. Plenary does not copy existing media between backends.

  • Public assets must be publicly readable, either directly or through the CDN at your Public base URL.
  • Private assets are stored under {prefix}private/. Your bucket policy must not grant public read on that path, or private files become public. Plenary hands out short-lived signed URLs for private assets and never links to that path directly.
  • Key prefix lets one bucket hold more than one installation.
  • Public files are stored with Cache-Control: public, max-age=86400, so a browser or CDN may keep serving a file for up to a day after you make it private. Private files are not cached.

For private media in the Media Library, see Media Library.

Each AWS-backed setting (SES, End User Messaging, S3) carries its own access key ID and secret access key, entered on its own panel. You can use the same IAM user for all three or a separate least-privilege user for each.

Two plenary.yaml keys supply defaults when a site is created without them:

plenary.yaml
locale:
default: en-us
timezone: America/Denver
  • locale.default becomes a new site’s default locale when you do not choose one.
  • locale.timezone becomes a new site’s timezone (an IANA name). With no value, sites default to UTC.

After a site exists, change its locales and timezone on the site itself. See Sites and Localization.

Method Path Does
GET, PUT /api/v1/settings/email-sending Read or replace the email binding
POST /api/v1/settings/email-sending/test Send a test email: {"to": "you@example.com"}
GET, PUT /api/v1/settings/sms-sending Read or replace the SMS binding
POST /api/v1/settings/sms-sending/test Send a test code: {"to": "+15551234567"}
GET, PUT /api/v1/settings/file-storage Read or replace the storage backend
GET /api/v1/settings/message-deliveries?channel=email Recent sends (channel is email or sms)
GET, PUT /api/v1/settings/single-sign-on Read or replace the identity provider connection; see Single sign-on
POST /api/v1/settings/single-sign-on/test Check a connection without saving it
POST /api/v1/settings/single-sign-on/saml/regenerate-key Replace the SAML signing key pair

All require a super user’s session. A GET returns every provider’s block plus available_providers (or available_backends):

{
"enabled": true,
"provider": "ses",
"from_address": "cms@example.com",
"from_name": "Example CMS",
"reply_to": "",
"ses": {
"access_key_id": "AKIAEXAMPLE",
"secret_access_key_configured": true,
"secret_access_key_hint": "Q4bZ",
"region": "us-east-1",
"configuration_set": ""
},
"sendgrid": { "api_key_configured": false, "api_key_hint": "" },
"mandrill": { "api_key_configured": false, "api_key_hint": "" },
"smtp": {
"host": "",
"port": 0,
"username": "",
"password_configured": false,
"password_hint": "",
"tls_mode": "",
"timeout_seconds": 0
},
"available_providers": ["ses", "sendgrid", "mandrill", "smtp"]
}

On PUT, send the secret fields (secret_access_key, api_key, password, auth_token) only when you change them. With "enabled": false, the binding is saved without validation, so you can turn a channel off without completing its fields. Changes take effect without a restart.

Errors are listed under Settings errors.

On Plenary Cloud the platform provisions email, SMS, and storage, and owns your license. The console shows a Subscription page instead of Global Settings and License, and a Single Sign-On page of its own, because your identity provider is yours to connect. These endpoints answer 403 cloud_managed:

  • /api/v1/settings/email-sending and its /test
  • /api/v1/settings/sms-sending and its /test
  • /api/v1/settings/file-storage
  • /api/v1/settings/message-deliveries
  • /api/v1/license and /api/v1/settings/license

/api/v1/settings/single-sign-on works the same on Cloud as on a licensed self-hosted instance.

Sites, users, roles, API keys, metrics, and all content features work the same on Cloud and self-hosted. To check which edition you are talking to, GET /api/v1/health returns "edition": "cloud" or "on-prem". See Plenary Cloud.

  • Sites: per-site name, locales, timezone, and site webhooks.
  • Self-hosted: installing and configuring plenary.yaml.
  • Licensing: installing a license on a self-hosted instance.
  • Media Library: private assets and folders.