Submit

The submit call sends a piece of text to a predefined email address. This is primarily useful to submit anonymous contact forms.

Server setup

To send emails, you need to install a mail transfer agent (MTA) such as OpenSMTPD:

sudo apt install opensmtpd

Other supported MTAs are postfix and nullmailer.

You may also need to set up SPF/DKIM records for the envelope (Return-Path: ...) and sender (From: ...) addresses.

Account configuration

Submission forms are often publicly available. For that reason, a separate account should be set up for each form. The account must contain a submit section with the destination parameters:

{"candy/contact-form": {"key": "none", "submit": {"type": "email", "from": {"email": "website@example.com"}, "to": [{"email": "info@example.com"}], "reply to sender": true, "subject": "Inquiry {topic}", "text": "{message}\n\n{name}\n{email}"}}}

The following destination parameters can be specified:

type	Must be `"email"`. Other values are reserved for future use.
return path	The envelope sender address used in the SMTP `MAIL FROM:` command. If not set, the sender address is used. (optional)
from	The sender address.
to	A list of recipient addresses.
cc	A list of carbon copy addresses. (optional)
bcc	A list of hidden carbon copy addresses. (optional)
reply to sender	If set to true, the contact form `sender` address is used as reply-to address. (optional)
reply to	A reply-to address, if `reply to sender` is not set. (optional)
subject	The subject.
text	The plain text version of the email body.
html	The HTML version of the email body. (optional)

An address is written as follows:

{"name": "John Smith", "email": "john.smith@example.com"}

whereby the name is optional.

In the subject and body, {property} is replaced by the corresponding property value sent with the request.

JavaScript

Using Backend.js, a contact form (name, e-mail, message) can be submitted as follows:

const backend = new Backend('https://viereck.ch/backend');
const account = backend.account('your-account-id', '44705748... your-account-key');

sendButton.onclick = function(event) {
	const data = {
		sender: {
			name: name.value.trim(),
			email: email.value.trim()
			},
		name: name.value.trim(),
		email: email.value.trim(),
		topic: topic.value.trim(),
		message: message.value.trim()
		};

	account.submit(data, onDone, onError);

	function onDone(request) {
		successMessage.style.display = '';
		sendButton.style.display = 'none';
	}

	function onError(errorCode, request) {
		errorMessage.style.display = '';
	}
};

HTTP/REST Requests

Request

POST /backend/submit

Account: ACCOUNT ID

Timestamp: TIMESTAMP

Signature: SIGNATURE

{"topic": "...", "sender": {"name": "...", "email": ""}, "message": "..."}

Response

200 if the data was submitted

400 if the request was invalid

401 if the account ID or signature is missing or invalid

403 if the account is not configured for submit calls

Account ID

Account key

JSON