Email Delivery

Codesphere uses email for account and team workflows such as invitations and authentication messages. Email delivery is optional, but these workflows do not send messages unless either SendGrid or a custom SMTP server is configured.

Use a custom SMTP server

Add the SMTP connection settings under codesphere.email in config.yaml:

codesphere:
  email:
    provider: smtp
    smtp:
      host: smtp.example.com
      port: 587
      secure: false
      username: codesphere

provider must be smtp. Set secure: true for implicit TLS, commonly on port 465. Set it to false for a connection that can be upgraded with STARTTLS, commonly on port 587. Omit username when the server does not require authentication.

When the SMTP server requires a password, add it to prod.vault.yaml; never put it in config.yaml:

secrets:
  - name: smtpPassword
    fields:
      password: <smtp-password>

Configure username whenever smtpPassword is present. The password is optional when the selected server or authentication mechanism does not require one.

Use SendGrid's SMTP relay

Existing installations can continue to supply their SendGrid API key in the vault:

secrets:
  - name: sendGridApiKey
    fields:
      password: <sendgrid-api-key>

No email block is required for this option. The installer configures SendGrid's SMTP relay at smtp.sendgrid.net with username apikey, port 587, and secure: false. When both sendGridApiKey and custom SMTP settings are present, SendGrid takes precedence. Remove sendGridApiKey from the vault to switch an existing installation to the custom SMTP server.

Both sendGridApiKey and smtpPassword are optional installer secrets. If neither a SendGrid API key nor an SMTP host is configured, Codesphere starts normally but does not deliver email. It writes a warning and records only that an email would have been sent; it does not log the message contents.

For the complete schema and secret inventory, see Private cloud installer config reference and Private cloud installer vault secrets.