Kumi
2eed78b83e
Adding two config options to modify behavior Allow messages with empty body to be sent Automatically convert HTML to plain if none provided Version bump to 0.4
150 lines
5.6 KiB
YAML
150 lines
5.6 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
description: A simple endpoint to send email messages
|
|
version: '0.4'
|
|
title: EXPMail
|
|
contact:
|
|
email: support@kumi.systems
|
|
tags:
|
|
- name: sending
|
|
description: Sending out an email
|
|
paths:
|
|
/sender.php:
|
|
post:
|
|
tags:
|
|
- sending
|
|
summary: Send out an email
|
|
operationId: sendMail
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Mail'
|
|
description: Object defining the email message to be sent
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: The request was received and processed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: '"Success" if message was successfully sent, else "error"'
|
|
error:
|
|
type: string
|
|
description: 'Error message, only included if an error has occurred'
|
|
servers:
|
|
- url: 'https://expmail.kumi.live'
|
|
components:
|
|
schemas:
|
|
Config:
|
|
type: object
|
|
required:
|
|
- key
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: >
|
|
Key of the config setting
|
|
* `noconversion` - Do not automatically convert HTML to plain text if no plain text message is explicitly given
|
|
* `ignoredlfails` - If an attachment fails to download, just leave it out and continue processing the message
|
|
Placeholder:
|
|
type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Name of the placeholder - will be converted to ALL CAPS by the server if it isn't already
|
|
value:
|
|
type: string
|
|
description: Value to insert into placeholder
|
|
Attachment:
|
|
type: object
|
|
required:
|
|
- url
|
|
properties:
|
|
url:
|
|
type: string
|
|
format: url
|
|
description: URL from where to fetch the file to attach
|
|
filename:
|
|
type: string
|
|
description: 'File name to use for email attachment. If not set, defaults to name from Content-Disposition header of URL if it exists, else the base name of the URL.'
|
|
cid:
|
|
type: string
|
|
description: 'Content ID for the attachment, needed for embedded images - use something like `<img src="cid:YOUR_CID">` in your HTML code'
|
|
Recipient:
|
|
type: object
|
|
required:
|
|
- email
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: Email address of the recipient
|
|
name:
|
|
type: string
|
|
description: Name of the recipient
|
|
Mail:
|
|
type: object
|
|
required:
|
|
- recipients
|
|
- key
|
|
properties:
|
|
subject:
|
|
type: string
|
|
description: Subject of the email
|
|
html:
|
|
type: string
|
|
description: 'String containing the HTML content of the email. Takes precedence over `htmlurl` if provided. If both `html` and `text` or `texturl` are provided, or the `noconversion` config key is not provided, will create a multi-part MIME message.'
|
|
htmlurl:
|
|
type: string
|
|
description: 'String containing the URL to a file containing the HTML content of the email. Ignored if `html` if provided. If both `htmlurl` and `text` or `texturl` are provided, or the `noconversion` config key is not provided, will create a multi-part MIME message.'
|
|
text:
|
|
type: string
|
|
description: 'String containing the plain text content of the email. Takes precedence over `texturl` if provided. If both `text` and `html` or `htmlurl` are provided, will create a multi-part MIME message.'
|
|
texturl:
|
|
type: string
|
|
description: 'String containing the URL to a file containing the plain text content of the email. Ignored if `text` is provided. If both `texturl` and `html` or `htmlurl` are provided, will create a multi-part MIME message.'
|
|
sender:
|
|
allOf:
|
|
- description: '`Recipient` object to be used as "From:" address for the email'
|
|
- $ref: '#/components/schemas/Recipient'
|
|
recipients:
|
|
type: array
|
|
description: 'Array of `Recipient` objects to be used as "To:" addresses for the email'
|
|
items:
|
|
$ref: '#/components/schemas/Recipient'
|
|
ccs:
|
|
type: array
|
|
description: 'Array of `Recipient` objects to be used as "CC:" addresses for the email'
|
|
items:
|
|
$ref: '#/components/schemas/Recipient'
|
|
bccs:
|
|
type: array
|
|
description: 'Array of `Recipient` objects to be used as "BCC:" addresses for the email'
|
|
items:
|
|
$ref: '#/components/schemas/Recipient'
|
|
attachments:
|
|
type: array
|
|
description: Array of `Attachment` objects to be attached to the email
|
|
items:
|
|
$ref: '#/components/schemas/Attachment'
|
|
placeholders:
|
|
type: array
|
|
description: 'Array of `Placeholder` objects. Any occurrences of `{PLACEHOLDER_NAME}` (`name` in all caps enclosed with curly brackets) in the email''s HTML or plain text will be replaced by `value`.'
|
|
items:
|
|
$ref: '#/components/schemas/Placeholder'
|
|
config:
|
|
type: array
|
|
description: 'Array of `Config` objects to change the endpoint\'s default behaviour'
|
|
items:
|
|
$ref: '#/components/schemas/Config'
|
|
key:
|
|
type: string
|
|
description: API key to authenticate request with
|