Inbound Email Configuration¶

Convert incoming emails into issues and comments automatically. This guide covers setting up email-to-issue functionality for your organization.

Overview¶

Kiket's inbound email feature allows you to:

Create issues from incoming emails automatically
Route emails to specific projects based on the recipient address
Add comments to existing issues via email replies
Apply sender policies to control who can create issues
Send auto-reply confirmations with custom templates
Optionally anchor email records to blockchain for compliance

Quick Start¶

Configure your email mapping in .kiket/inbound_email.yaml
Set up DNS to point your inbound email domain to Kiket's email provider
Deploy your workflow repository changes

Configuration¶

Basic Setup¶

Create .kiket/inbound_email.yaml in your workflow repository:

inbound_email:
  enabled: true
  mappings:
    - email_address: support@acme.inbound.kiket.dev
      sender_policy: open
      issue_defaults:
        issue_type: Ticket
        priority: medium
        status: todo
      auto_reply: true
      auto_reply_template: confirmation

Email Address Mappings¶

Each mapping connects an email address to a project with specific defaults:

mappings:
  - email_address: support@acme.inbound.kiket.dev
    description: Customer support inbox
    sender_policy: open
    issue_defaults:
      issue_type: Ticket
      priority: medium
      status: todo
      labels:
        - support
        - incoming
    auto_reply: true
    auto_reply_template: confirmation
    blockchain_anchoring: false

  - email_address: bugs@acme.inbound.kiket.dev
    description: Bug reports
    sender_policy: known_users
    issue_defaults:
      issue_type: Bug
      priority: high
      labels:
        - bug
        - needs-triage
    auto_reply: true
    auto_reply_template: bug_received

Sender Policies¶

Control who can create issues via email:

Policy	Description
`open`	Anyone can send emails (default)
`known_users`	Only organization members can send
`known_domains`	Only addresses from domains with existing org members

# Allow anyone
sender_policy: open

# Only registered users
sender_policy: known_users

# Only company domain emails
sender_policy: known_domains

Issue Defaults¶

Set default values for issues created from emails:

issue_defaults:
  issue_type: Task          # Task, Bug, Story, Epic, etc.
  priority: medium          # low, medium, high, critical
  status: todo              # Initial workflow state
  labels:                   # Array of labels
    - support
    - email
  # assigned_to: user@example.com  # Default assignee (optional)

Auto-Reply Templates¶

Create Liquid templates in .kiket/email_templates/:

{# .kiket/email_templates/confirmation.liquid #}
<p>Hello {{ inbound_email.from_name | default: "there" }},</p>

<p>Thank you for contacting {{ organization.name }}. We've received your message and created a support ticket.</p>

{% if issue %}
<p>
  <strong>Reference:</strong> {{ issue.key }}<br>
  <strong>Subject:</strong> {{ issue.title }}
</p>

<p>You can track your request at: <a href="{{ issue.url }}">{{ issue.url }}</a></p>
{% endif %}

<p>Our team will respond as soon as possible.</p>

<p>
  Best regards,<br>
  {{ organization.name }} Support Team
</p>

Available Template Variables¶

Variable	Description
`inbound_email.from_name`	Sender's display name
`inbound_email.from_email`	Sender's email address
`inbound_email.subject`	Email subject line
`issue.key`	Issue key (e.g., PRJ-123)
`issue.title`	Issue title
`issue.url`	Link to the issue
`issue.status`	Current status
`issue.priority`	Priority level
`organization.name`	Organization name
`organization.subdomain`	Organization subdomain
`project.name`	Project name
`project.key`	Project key

Reply Threading¶

Kiket automatically threads email replies to existing issues:

Reply-To Address: Issues include a reply-to address like issue+123@acme.inbound.kiket.dev
Subject Line: Replies with [PRJ-123] in the subject are matched
In-Reply-To Header: Standard email threading headers are respected

Replies become comments on the original issue.

Blockchain Anchoring¶

For compliance-heavy workflows, enable blockchain anchoring:

mappings:
  - email_address: legal@acme.inbound.kiket.dev
    blockchain_anchoring: true
    # ... other settings

This creates tamper-evident records of all inbound emails for audit trails.

DNS Configuration¶

Set up your inbound email domain by configuring MX records:

inbound.yourdomain.com   MX   10   inbound.kiket.dev

Contact support for specific DNS setup instructions for your email provider.

CLI Validation¶

Validate your inbound email configuration:

# Lint all definitions including inbound_email.yaml
kiket definitions lint

# Skip inbound email linting
kiket definitions lint --no-inbound-email

Email Address Format¶

Supported inbound email patterns:

support@{subdomain}.inbound.kiket.dev - Standard inbox
issue+{id}@{subdomain}.inbound.kiket.dev - Reply to specific issue
Custom domains with configured DNS

Security Considerations¶

Sender Verification: Use known_users or known_domains for sensitive projects
Rate Limiting: Built-in protection against email flooding
Spam Prevention: Consider combining with your email provider's spam filtering
Attachment Handling: Attachments are stored securely but not processed for content

Troubleshooting¶

Emails Not Creating Issues¶

Check that the email address mapping exists and is active
Verify sender policy allows the sender
Review processing logs in admin panel
Ensure DNS is correctly configured

Replies Not Threading¶

Verify the email contains proper Reply-To or In-Reply-To headers
Check that the issue reference [PRJ-123] is in the subject
Confirm the issue exists and hasn't been deleted

Auto-Replies Not Sending¶

Verify auto_reply: true in the mapping
Check that auto_reply_template points to a valid template
Review email delivery logs

API Reference¶

Receive Inbound Email¶

Extensions can send normalized email payloads to the Extension API:

POST /api/v1/ext/inbound_emails
Authorization: Bearer {runtime_token}

{
  "message_id": "unique-message-id@example.com",
  "from_email": "sender@example.com",
  "from_name": "Sender Name",
  "to_email": "support@acme.inbound.kiket.dev",
  "subject": "Help request",
  "text_body": "Email content...",
  "html_body": "<p>Email content...</p>"
}

See the [Extension API documentation(../extensions/api.md) for details.

[Configuration Reference(../reference/configuration.md) - Full YAML schema reference
[Workflow Repository Setup(workflow-repo-seeding.md) - Setting up definition repos
[Blockchain Audit Trails(../platform/blockchain-audit-trails.md) - Compliance features
[Email Notification Preferences(team-onboarding.md) - Managing email settings