Skip to main content

Email trigger

An email-triggered skill runs when mail arrives for an address it claims. The whole message — headers, body, attachments — is passed to the agent.

Use it for intake from people rather than systems: a support address that turns threads into triaged bugs, a deploy-requests@ address, anything already reaching your team by mail.

---
name: email-bug-intake
description: Turn a support mail thread into a triaged Issue Tracker bug.
disable-model-invocation: true
x-codee-trigger: email
x-codee-email-address: bugs@codee.example.com
---

How delivery works​

Codee reads mail from one of two places.

Mailpit. If MAILPIT_API_URL is set, Codee asks Mailpit once a minute for mail sent to your skills' addresses. Other mail in Mailpit is left alone. When Codee is done with a message, it deletes it from Mailpit. See Integrating with Mailpit for the setup.

VariableExampleWhat it is
MAILPIT_API_URLhttp://localhost:8025/api/v1Mailpit API base URL
MAILPIT_AUTHuser:passwordMailpit user name and password, if it has one

A folder. If MAILPIT_API_URL is not set, Codee reads a folder:

incoming mail → temp-emails/*.eml → the tick routes each file to a skill

Anything that writes an .eml file into temp-emails/ in your Codee project directory feeds the trigger — the SMTP server Codee ships with, a procmail rule, a fetchmail cron job, a script against your IMAP mailbox. The SMTP server is the shortest path, not the only one.

Setup​

1. Allow the sender domains​

export CODEE_ALLOWED_SENDER_DOMAINS=yourcompany.com,partner.example

Mail from any other domain is dropped without running anything.

This variable is not optional

It is empty by default, and an empty list allows nothing. Until you set it, every email is deleted and no skill runs. This includes mail in Mailpit.

Codee reads it only when it starts, and only from its environment, not from .env. Restart Codee after you change it. If you use pm2, load .env in your shell before the restart, or Codee starts without it.

An email address is trivial to forge, so treat this as a filter, not authentication. Do not put an address that accepts mail from the public internet behind a skill that can change code.

2. Get the mail to Codee​

If you use Mailpit, follow Integrating with Mailpit and go on to step 3.

Otherwise run the SMTP server Codee ships with. It is a separate process — codee-start does not launch it:

MAIL_PORT=2525 uv run python -m codee.mail_server
VariableDefaultWhat it is
MAIL_HOST0.0.0.0interface to listen on
MAIL_PORT2525port to listen on

It listens unprivileged on purpose. Map port 25 to it at the infrastructure layer with iptables or a load balancer rather than running Codee as root. Put it behind your own MX or a relay; it does not do TLS, authentication or spam filtering itself.

Each accepted message is written to a .eml file, with the envelope recipients prepended as an X-Codee-Rcpt header so routing matches the real RCPT TO rather than only the visible To.

Check where the files land

The server saves mail to a temp-emails/ folder next to Codee's own code. Codee reads mail from the temp-emails/ folder in your project. These are two different folders, so by default the mail is never picked up. Send one test message and find the .eml file. If it is not in your project's temp-emails/, link that folder to your project, or use Mailpit instead.

3. Declare the trigger​

x-codee-trigger: email
x-codee-email-address: bugs@codee.example.com

The address is matched case-insensitively against every recipient of the message, in this order: X-Codee-Rcpt, Delivered-To, To, Cc, Bcc. The first skill that matches runs.

One address belongs to one skill. If two skills claim the same address, Codee keeps the first and logs a warning about the other.

In the UI, pick email trigger as the Skill type and fill in Email address.

4. Write the prompt​

Put {CONTENT} where the message should go:

# Email Bug Intake

A bug report arrived by email:

{CONTENT}

1. Read the whole thread, including quoted replies and attachments.
2. Extract the reported behaviour, the expected behaviour, and the environment.
3. Search the Issue Tracker for a duplicate before creating anything.
4. Create the bug with a reproduction, severity, and the affected component.
5. Reply to the reporter with the issue key.

Leave {CONTENT} out and the message is appended to the end of the body instead.

What the agent receives is:

  • every header, one per line;
  • the body, plain text preferred and HTML as a fallback;
  • a list of attachments, each saved to a temporary file and given by path, so the agent can open a screenshot or a log.

Ask for a duplicate check. An address people can mail is an address people mail twice.

5. Send a test message​

swaks --to bugs@codee.example.com --from you@yourcompany.com \
--server localhost:2525 --body 'Checkout fails with a 500 on the payment step.'

The run appears on the Runs page within a minute.

How a message is handled​

  1. Once a minute, Codee takes up to three messages, oldest first, for all email skills together.
  2. A message from a domain outside CODEE_ALLOWED_SENDER_DOMAINS is deleted and nothing runs.
  3. A message that no skill's address matches is deleted and nothing runs. (With Mailpit this doesn't happen, because Codee only asks for mail sent to your skills.)
  4. Otherwise the prompt is rendered and the agent runs.
  5. On success, or when the run is stopped from the dashboard, the message is deleted.
  6. On failure the message is kept and tried again on a later tick.

Things worth knowing​

  • A failing message retries forever. Point 6 has no attempt limit. If a skill keeps failing on one email, the fix is to delete the .eml file from temp-emails/, or the message from Mailpit.
  • Three per tick. A backlog drains at three messages a minute at best, and slower when runs are long, because each run blocks the tick.
  • No reply is sent for you. If the reporter should hear back, say so in the skill body and give the agent a way to send it.
  • Attachments are written to a temporary directory outside the project. They are not cleaned up by Codee.