feat(api): Add SMTP over HTTP REST API endpoint

[tayyebi]

Contribution Guidelines

• I've read the contribution guidelines and wholeheartedly agree them

What does this PR include?

Short Description

Adds a new REST API endpoint POST /api/v1/send/email that allows mailbox users to send emails programmatically via SMTP through HTTP requests.

Key Features:

• Send emails with plain text and/or HTML body
• Support for multiple recipients (To, CC, BCC)
• Reply-to address support
• Base64 encoded file attachments
• Mailbox-level authentication required (smtp_user + password)
• Sender authorization enforced (same rules as SMTP: own mailbox, aliases, sender ACL)

Request Parameters:

Field	Type	Required	Description
from	string	Yes	Sender email address
to	array	Yes	Array of recipient email addresses
subject	string	Yes	Email subject
body	string	Yes	Plain text email body
smtp_user	string	Yes	SMTP username (mailbox login)
password	string	Yes	SMTP password (mailbox login)
html_body	string	No	HTML email body
cc	array	No	CC email addresses
bcc	array	No	BCC email addresses
reply_to	string	No	Reply-to email address
attachments	array	No	Base64 encoded attachments
smtp_host	string	No	SMTP server (default: postfix-mailcow)
smtp_port	integer	No	SMTP port (default: 587)

Example:

curl -X POST 'https://mail.example.com/api/v1/send/email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR-API-KEY' \
  -d '{"from":"user@example.com","to":["recipient@example.com"],"subject":"Test","body":"Hello","smtp_user":"user@example.com","password":"mailbox-password"}'

Affected Containers

• php-fpm-mailcow

Did you run tests?

What did you tested?

• Sending basic emails with authentication
• Sending HTML emails with CC/BCC
• Attachments (base64 encoded)
• Sender authorization (own mailbox, aliases, sender ACL)
• Error handling for invalid addresses, missing fields
• Unauthorized sender rejection

What were the final results? (Awaited, got)

All test cases passed. Emails are sent correctly when mailbox credentials are provided and sender is authorized. Unauthorized senders receive appropriate error messages.

Related

• Documentation: docs: Add SMTP API documentation mailcow-dockerized-docs#920

[milkmaker]

Thanks for contributing!

I noticed that you didn't select staging as your base branch. Please change the base branch to staging.
See the attached picture on how to change the base branch to staging:

[dragoangel]

How this going to work with current API when API key is only used for administrative automation and not even generated per domain. This is wrong by design.

[tayyebi]

i was trying to keep the code self-describing. and also i have updated the openapi as well to let users know that they can (and mailcow prefers them) to use app_password instead of their mailbox password. 299a815

-      $smtp_pass = isset($data['password']) ? $data['password'] : '';
+      $smtp_pass = $data['app_password'] ?? $data['password'] ?? '';