Klaus-Uwe Mitterer
730ad8c0e1
Implement warning output Implement warning when URL and string provided for HTML/plain Turn allowempty to config key Add option to prefer URL over string for HTML/plain Add user agent to curl requests Update OpenAPI Bump version to 0.5
151 lines
5.9 KiB
YAML
151 lines
5.9 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
description: A simple endpoint to send email messages
|
|
version: '0.5'
|
|
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'
|
|
warning:
|
|
type: array
|
|
description: 'Array of warning messages generated during the sending process, if any'
|
|
items:
|
|
type: string
|
|
|
|
servers:
|
|
- url: 'https://expmail.kumi.live'
|
|
components:
|
|
schemas:
|
|
Config:
|
|
type: string
|
|
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` keys to change the default behaviour
|
|
* `allowempty` - Allow messages to have an empty body, would otherwise return an error
|
|
* `ignoredlfails` - If an attachment fails to download, just leave it out and continue processing the message
|
|
* `noconversion` - Do not automatically convert HTML to plain text if no plain text message is explicitly given
|
|
* `urlbeforestring` - If both a string and a URL are given for the HTML or plain text content, prefer URL (else: prefer string)
|
|
items:
|
|
$ref: '#/components/schemas/Config'
|
|
key:
|
|
type: string
|
|
description: API key to authenticate request with
|