Skip to content

Commit ab42876

Browse files
tayyebitayyebi
committed
feat(api): Add SMTP over HTTP REST API endpoint
Adds a new API endpoint POST /api/v1/send/email for sending emails programmatically via SMTP. Features: - Send emails with plain text and/or HTML body - Support for CC, BCC, and reply-to addresses - Base64 encoded file attachments - Configurable SMTP host, port, and authentication - Full validation of email addresses - Proper error handling with descriptive messages Files changed: - data/web/inc/functions.inc.php: Added smtp_api() function - data/web/json_api.php: Added 'send' action handler - data/web/api/openapi.yaml: Added endpoint documentation - data/web/lang/lang.en-gb.json: Added error/success messages
1 parent 038b2ef commit ab42876

File tree

4 files changed

+456
-0
lines changed

4 files changed

+456
-0
lines changed

‎data/web/api/openapi.yaml‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6047,6 +6047,152 @@ paths:
60476047
ignore_ssl_error: true
60486048
summary: Edit external Identity Provider
60496049

6050+
/api/v1/send/email:
6051+
post:
6052+
responses:
6053+
"401":
6054+
$ref: "#/components/responses/Unauthorized"
6055+
"200":
6056+
content:
6057+
application/json:
6058+
examples:
6059+
response:
6060+
value:
6061+
- type: success
6062+
msg:
6063+
- smtp_mail_sent
6064+
- sender@domain.tld
6065+
- recipient@domain.tld
6066+
schema:
6067+
properties:
6068+
type:
6069+
enum:
6070+
- success
6071+
- error
6072+
type: string
6073+
msg:
6074+
items: {}
6075+
type: array
6076+
type: object
6077+
description: OK
6078+
"400":
6079+
content:
6080+
application/json:
6081+
schema:
6082+
properties:
6083+
type:
6084+
type: string
6085+
example: error
6086+
msg:
6087+
type: array
6088+
items: {}
6089+
type: object
6090+
description: Bad Request - Validation error or SMTP failure
6091+
tags:
6092+
- SMTP
6093+
description: >-
6094+
Send an email via SMTP using the mailcow SMTP API. This endpoint allows
6095+
you to send emails programmatically with support for HTML content,
6096+
attachments, CC, BCC, and custom SMTP settings.
6097+
6098+
6099+
**Authentication**: Requires a read-write API key.
6100+
6101+
6102+
**Note**: When using authenticated SMTP (port 587 with STARTTLS or port 465 with SSL),
6103+
provide the password field. For unauthenticated internal sending (port 25),
6104+
the password can be omitted.
6105+
operationId: Send email
6106+
requestBody:
6107+
content:
6108+
application/json:
6109+
schema:
6110+
example:
6111+
from: sender@domain.tld
6112+
to:
6113+
- recipient@domain.tld
6114+
subject: Test Subject
6115+
body: This is the plain text body
6116+
html_body: "<html><body><h1>Hello</h1><p>This is HTML content</p></body></html>"
6117+
cc:
6118+
- cc@domain.tld
6119+
bcc:
6120+
- bcc@domain.tld
6121+
reply_to: reply@domain.tld
6122+
attachments:
6123+
- filename: document.pdf
6124+
content: base64encodedcontent
6125+
content_type: application/pdf
6126+
smtp_host: postfix-mailcow
6127+
smtp_port: 25
6128+
smtp_user: sender@domain.tld
6129+
password: yourpassword
6130+
properties:
6131+
from:
6132+
description: Sender email address
6133+
type: string
6134+
to:
6135+
description: Array of recipient email addresses
6136+
type: array
6137+
items:
6138+
type: string
6139+
subject:
6140+
description: Email subject
6141+
type: string
6142+
body:
6143+
description: Plain text email body
6144+
type: string
6145+
html_body:
6146+
description: HTML email body (optional)
6147+
type: string
6148+
cc:
6149+
description: Array of CC email addresses (optional)
6150+
type: array
6151+
items:
6152+
type: string
6153+
bcc:
6154+
description: Array of BCC email addresses (optional)
6155+
type: array
6156+
items:
6157+
type: string
6158+
reply_to:
6159+
description: Reply-to email address (optional)
6160+
type: string
6161+
attachments:
6162+
description: Array of attachments with base64 encoded content (optional)
6163+
type: array
6164+
items:
6165+
type: object
6166+
properties:
6167+
filename:
6168+
type: string
6169+
description: Attachment filename
6170+
content:
6171+
type: string
6172+
description: Base64 encoded file content
6173+
content_type:
6174+
type: string
6175+
description: MIME content type
6176+
smtp_host:
6177+
description: SMTP server host (default postfix-mailcow)
6178+
type: string
6179+
smtp_port:
6180+
description: SMTP server port (default 25 for internal, use 587 for authenticated)
6181+
type: integer
6182+
smtp_user:
6183+
description: SMTP username (default same as from)
6184+
type: string
6185+
password:
6186+
description: SMTP password for authentication
6187+
type: string
6188+
required:
6189+
- from
6190+
- to
6191+
- subject
6192+
- body
6193+
type: object
6194+
summary: Send email via SMTP
6195+
60506196
tags:
60516197
- name: Domains
60526198
description: You can create antispam whitelist and blacklist policies
@@ -6094,3 +6240,5 @@ tags:
60946240
description: Manage Cross-Origin Resource Sharing (CORS) settings
60956241
- name: Identity Provider
60966242
description: Manage external Identity Provider settings
6243+
- name: SMTP
6244+
description: Send emails programmatically via SMTP

0 commit comments

Comments
 (0)