Merge pull request #226 from christianlouis/copilot/fix-smtp-fallback-issues

fix: add sender_email to SMTP config to decouple auth credential from From: header

CHANGELOG.md

@@ -17,6 +17,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## v0.10.0 (2026-05-03)
 
+### Bug Fixes
+
+- **SMTP Fallback sender address**: Add `sender_email` field to `UserSmtpConfig` so the SMTP `From:` header uses a real email address instead of the SMTP authentication token. Providers like Postmark use a UUID API token as the username, which caused a `501 Bad sender address syntax` error. The new field is optional; when left blank the `username` value is used as a fallback (preserving existing behaviour for providers where username == email address). Includes a new Alembic migration (`0003`) and a Sender Email input in the Settings page.
+
 
 ## v0.9.2 (2026-05-03)
 

backend/alembic/versions/0003_add_smtp_sender_email.py

@@ -0,0 +1,36 @@
+"""Add sender_email column to user_smtp_configs
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-05-03
+
+Adds a ``sender_email`` column to ``user_smtp_configs``.
+
+SMTP providers such as Postmark use an API token (UUID) as the SMTP username
+for authentication, but require a real email address as the ``From:`` header.
+This column stores the address that should appear as the sender; when blank,
+the existing ``username`` value is used as a fallback so existing rows remain
+fully functional.
+
+Using IF NOT EXISTS makes the migration idempotent against fresh installs
+where create_all() already created the column.
+"""
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "0003"
+down_revision = "0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "ALTER TABLE user_smtp_configs "
+        "ADD COLUMN IF NOT EXISTS sender_email VARCHAR(255) NOT NULL DEFAULT ''"
+    )
+
+
+def downgrade() -> None:
+    op.execute("ALTER TABLE user_smtp_configs DROP COLUMN IF EXISTS sender_email")

backend/app/api/v1/endpoints/users.py

@@ -72,6 +72,7 @@ async def get_smtp_config(
         host=config.host,  # type: ignore[arg-type]
         port=config.port,  # type: ignore[arg-type]
         username=config.username,  # type: ignore[arg-type]
+        sender_email=config.sender_email,  # type: ignore[arg-type]
         use_tls=config.use_tls,  # type: ignore[arg-type]
         has_password=bool(config.encrypted_password),
         created_at=config.created_at,  # type: ignore[arg-type]
@@ -95,6 +96,7 @@ async def upsert_smtp_config(
         config.host = config_in.host  # type: ignore[assignment]
         config.port = config_in.port  # type: ignore[assignment]
         config.username = config_in.username  # type: ignore[assignment]
+        config.sender_email = config_in.sender_email  # type: ignore[assignment]
         config.use_tls = config_in.use_tls  # type: ignore[assignment]
         if config_in.password is not None:
             config.encrypted_password = encrypt_credential(config_in.password)  # type: ignore[assignment]
@@ -104,6 +106,7 @@ async def upsert_smtp_config(
             host=config_in.host,
             port=config_in.port,
             username=config_in.username,
+            sender_email=config_in.sender_email,
             encrypted_password=(
                 encrypt_credential(config_in.password) if config_in.password else ""
             ),
@@ -120,6 +123,7 @@ async def upsert_smtp_config(
         host=config.host,  # type: ignore[arg-type]
         port=config.port,  # type: ignore[arg-type]
         username=config.username,  # type: ignore[arg-type]
+        sender_email=config.sender_email,  # type: ignore[arg-type]
         use_tls=config.use_tls,  # type: ignore[arg-type]
         has_password=bool(config.encrypted_password),
         created_at=config.created_at,  # type: ignore[arg-type]
@@ -174,7 +178,7 @@ async def test_smtp_config(
             "plain",
             "utf-8",
         )
-        msg["From"] = config.username  # type: ignore[index]
+        msg["From"] = config.sender_email or config.username  # type: ignore[index]
         msg["To"] = recipient
         msg["Date"] = formatdate(localtime=True)
         msg["Message-ID"] = make_msgid()

backend/app/models/database_models.py

@@ -475,6 +475,7 @@ class UserSmtpConfig(Base):
     username = Column(String(255), nullable=False, default="")
     encrypted_password = Column(Text, nullable=False, default="")
     use_tls = Column(Boolean, default=True)
+    sender_email = Column(String(255), nullable=False, default="")
 
     created_at = Column(
         DateTime(timezone=True),

backend/app/models/schemas.py

@@ -481,6 +481,7 @@ class UserSmtpConfigBase(BaseModel):
     host: str = "smtp.gmail.com"
     port: int = Field(587, gt=0, lt=65536)
     username: str = ""
+    sender_email: str = ""
     use_tls: bool = True
 
 

backend/app/services/mail_processor.py

@@ -1256,7 +1256,9 @@ class MailProcessor:
 
                 # Create forwarding message
                 forward_msg = MIMEMultipart("mixed")
-                forward_msg["From"] = smtp_config["username"]
+                forward_msg["From"] = (
+                    smtp_config.get("sender_email") or smtp_config["username"]
+                )
                 forward_msg["To"] = destination
                 forward_msg["Date"] = formatdate(localtime=True)
                 forward_msg["Message-ID"] = make_msgid()

backend/app/workers/tasks.py

@@ -210,6 +210,7 @@ async def process_mail_account(account_id: int):
                         "host": user_smtp.host,
                         "port": user_smtp.port,
                         "username": user_smtp.username,
+                        "sender_email": user_smtp.sender_email or "",
                         "password": decrypt_credential(user_smtp.encrypted_password),  # type: ignore[arg-type]
                         "use_tls": user_smtp.use_tls,
                     }

frontend/src/app/settings/page.tsx

@@ -148,6 +148,7 @@ function SettingsContent() {
     host: 'smtp.gmail.com',
     port: 587,
     username: '',
+    sender_email: '',
     password: '',
     use_tls: true,
   });
@@ -187,6 +188,7 @@ function SettingsContent() {
       host: smtpConfig.host,
       port: smtpConfig.port,
       username: smtpConfig.username,
+      sender_email: smtpConfig.sender_email,
       use_tls: smtpConfig.use_tls,
       password: '', // never pre-fill password
     }));
@@ -246,7 +248,7 @@ function SettingsContent() {
     mutationFn: smtpApi.remove,
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['smtp-config'] });
-      setSmtpForm({ host: 'smtp.gmail.com', port: 587, username: '', password: '', use_tls: true });
+      setSmtpForm({ host: 'smtp.gmail.com', port: 587, username: '', sender_email: '', password: '', use_tls: true });
     },
   });
 
@@ -302,6 +304,7 @@ function SettingsContent() {
         host: smtpForm.host,
         port: smtpForm.port,
         username: smtpForm.username,
+        sender_email: smtpForm.sender_email,
         password: smtpForm.password || undefined,
         use_tls: smtpForm.use_tls,
       });
@@ -601,6 +604,21 @@ function SettingsContent() {
                 />
               </div>
 
+              <div>
+                <label className="block text-sm font-medium text-gray-700 mb-1">Sender Email</label>
+                <input
+                  type="email"
+                  name="sender_email"
+                  value={smtpForm.sender_email}
+                  onChange={handleSmtpChange}
+                  className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+                  placeholder="sender@example.com"
+                />
+                <p className="mt-1 text-xs text-gray-500">
+                  The From: address used when forwarding mail. Required when your SMTP username is an API token rather than an email address (e.g. Postmark, SendGrid).
+                </p>
+              </div>
+
               <div>
                 <label className="block text-sm font-medium text-gray-700 mb-1">Password</label>
                 <input

frontend/src/lib/api.ts

@@ -224,6 +224,7 @@ export interface UserSmtpConfig {
   host: string;
   port: number;
   username: string;
+  sender_email: string;
   use_tls: boolean;
   has_password: boolean;
   created_at: string;
@@ -485,6 +486,7 @@ export const smtpApi = {
     host: string;
     port: number;
     username: string;
+    sender_email: string;
     password?: string;
     use_tls: boolean;
   }): Promise<UserSmtpConfig> {