You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

Email relay

Corteza allows you to detect and react to incoming emails via automation scripts. You can implement automatic responses, create records based on the email content, and forward the email to our supervisor.

Here, we only cover how to setup an email relay. Refer to the integrator guide for details on using this feature.

DevNote provide a nice little diagram outlining this.

Flow outline:
  1. Postfix (or similar) forwards the email to the sink API endpoint,

  2. Corteza sink service processes the payload to prepare an automation script event,

  3. the event is dispatched on the event bus, executing any automation scripts that match the event constraints.

Corteza setup

Under the hood, email relays use sink routes, so we need to generate a sink route signature. See Sink routes on how to set that up.

Make sure to specify a --content-type email.

Postfix setup

Make sure to change the parameters to fit your environment.

Edit /etc/postfix/main.cf:
virtual_alias_maps = pcre:/etc/postfix/virtual_alias
Add virtual alias to /etc/postfix/virtual_alias:
# Catch-all for corteza.domain.tld and redirect it to corteza_sink mailbox
/.+@corteza\.domain\.tld$/ corteza_sink
Update virtual-alias map/db file, and restart postfix
postmap /etc/postfix/virtual_alias
postfix reload
Add entry to /etc/aliases
corteza_sink: "| curl --data-binary @- 'https://api.your-corteza-instance.tld/system/sink?content-type=email&expires=&method=POST&origin=postfix&__sign=187...3D'"

The above forwards any email for a specific mailbox to a curl command, which then pushes that raw email to the sink endpoint on the Corteza API.

Update aliases
newaliases

Testing Postfix changes

We recommend using a different machine — one that is not running postfix.

You can verify if everything works correctly by either sending an email to the configured address or with a simple CLI command:

# Make sure to change `test@corteza.domain.tld`.
echo "hello corteza"|mail -s 'hello' test@corteza.domain.tld

This should produce a new entry in your mail log (usually /var/log/mail.log) for the test email, along with a log that looks something in the lines of:

postfix/smtpd[23155]: connect from some-host.tld[xxx.xxx.xxx.xxx]
postfix/smtpd[23155]: 277AF5C1B78: client=some-host.tld[xxx.xxx.xxx.xxx]
postfix/cleanup[23159]: 277AF5C1B78: message-id=<b808218e-ce41-6cbf-cb4f-be2b4cf8f776@crust.tech>
postfix/qmgr[14490]: 277AF5C1B78: from=<sender@some-host.tld>, size=1476, nrcpt=1 (queue active)
postfix/smtpd[23155]: disconnect from some-host.tld[xxx.xxx.xxx.xxx] ehlo=2 starttls=1 mail=1 rcpt=1 data=1 quit=1 commands=7
postfix/local[23160]: 277AF5C1B78: to=<corteza_sink@my-server>, orig_to=<demo@corteza.domain.tld>, relay=local, delay=0.67, delays=0.03/0.01/0/0.62, dsn=2.0.0, status=sent (delivered to command:  curl --data-binary @- 'https://api.your-corteza-instance.tld/system/sink?content-type=email&expires=&method=POST&origin=postfix&__sign=187...3D')
postfix/qmgr[14490]: 277AF5C1B78: removed

If nothing happens when you send an email, there could be a firewall issue and blocked ports.

Testing Corteza

To test if your sink signature and automaton script are setup correctly, you can use the following command:

echo "
From: <sender@cortezaproject.org>
To: <test@corteza.domain.tld>
Subject: hello
Message-ID: <1234@local.machine.example>

Ola Corteza!
" | curl -i --data-binary @- "https://api.your-corteza-instance.tld/system/sink?content-type=email&expires=&method=POST&origin=postfix&__sign=187...3D"

If this command does not return a 200 OK response, it means that something is misconfigured. Refer to system logs to see exactly where the issue lies.