Email remains a common entry point for bug reports, support requests, and operational alerts. Manually copying those messages into Jira, Linear, or GitHub loses context and delays triage. Automation can preserve the source reference and apply consistent routing, but it should not turn every message into an unrestricted command.
Relay does not need a native integration for each tracker. Build a generic adapter that polls the Relay REST API, normalizes messages into an internal work item, applies your mapping rules, and calls the tracker's official API. Durable dedupe and conservative permissions make the pattern reliable across all three destinations.
Use a polling adapter and a neutral work item
The adapter reads GET https://www.relaymcp.net/api/v1/inboxes/:id/messages with Bearer authentication, limit, and a saved cursor. It can retrieve full content with GET /inboxes/:id/messages/:messageId. Validate responses against the current Relay API documentation before mapping them into internal fields.
Define a neutral representation so tracker-specific code stays small:
WorkItem {
sourceInboxId, sourceMessageId, sourceHash,
title, description, labels, priorityHint,
requesterReference, targetProject, approvalState
}
A pipeline can then be poll -> normalize -> policy checks -> dedupe -> create or update -> record mapping. Store the Relay cursor only after source processing is recoverable. Store tracker issue keys alongside the source identity so restarts reconcile rather than recreate.
Use separate credentials for Relay and each tracker. Relay authenticates with process.env.RELAY_API_KEY; Jira, Linear, and GitHub tokens belong in distinct server-side secrets with only the project scopes required. Never put tokens in issue descriptions, links, or logs.
Map fields explicitly and conservatively
Do not pass arbitrary email headers or body markup into a tracker API. Construct each field in code and preserve a reference to the source message for authorized review. The same neutral item can produce different output without changing ingestion.
| Internal field | Jira | Linear | GitHub |
|---|---|---|---|
title |
summary | title | issue title |
description |
description document | markdown description | issue body |
targetProject |
project key | team or project | owner and repository |
labels |
labels | label identifiers | repository labels |
requesterReference |
allowed custom field | text or link | body reference |
Use fixed labels and priorities from your own routing table. Sender-supplied text such as 'priority: critical' should be a hint, not authority. Tracker Markdown, Jira document structures, and HTML have different escaping rules; build each target from plain normalized text rather than reusing one rendered payload.
Keep the description bounded. Long messages can be truncated at a documented limit with a source reference, while attachments should go through the separate controls in the secure attachment guide. Do not automatically attach or preview every file.
Deduplicate across polling and tracker retries
Use a unique key based on inbox ID and message ID for creation. A body hash can identify accidental reposts, but it should not replace source identity because distinct messages can be identical. Add a database unique constraint and perform the dedupe check in the same transaction as your outbox creation.
Tracker creation introduces a second ambiguity: your request may succeed while the response times out. Where the official API supports an idempotency mechanism, use it. Otherwise, record an attempt before sending and reconcile by searching a controlled external reference or known mapping before retrying. Avoid repeated blind creation.
source_key = relay:inbox_id:message_id
unique(source_key)
pending -> creating -> linked
|
+-> needs_reconciliation -> linked or creating
For updates, define whether new mail creates a comment, reopens an item, or does nothing. Threading headers can help, but treat them as untrusted correlation hints. Require an existing authorized mapping before adding content to a tracker item.
Restrict permissions and automate approval boundaries
Run the adapter with a dedicated tracker identity, not an administrator's personal token. Limit it to selected projects or repositories and disallow changes to permissions, workflows, webhooks, or repository settings. Creating an issue does not require controlling the whole organization.
Some mail should enter a review queue instead of creating work: unknown senders, messages requesting privileged actions, content with suspicious links, or items that map to confidential projects. Approval should display the exact title, description, target, and labels. Bind approval to a payload hash so edits invalidate it.
Email is untrusted even when HTML is sanitized. A body saying 'close all issues' or 'add me as an admin' is content to summarize, not an instruction to execute. Expose only create or comment operations to the adapter; implement any higher-risk action as a separate authenticated workflow.
Make failures visible and recovery routine
Log source IDs, target project, attempt, response status, and tracker item key, but redact bodies, addresses, and tokens. Monitor polling lag, normalization failures, approval backlog, tracker rate limits, reconciliation cases, and duplicate prevention hits. Respect each official API's pagination and rate-limit rules rather than hardcoding one retry policy for every destination.
Test with synthetic messages for each mapping branch: long titles, Unicode, hostile markup, duplicate delivery, missing project configuration, expired tracker tokens, and timeouts after creation. Use a dedicated test project before enabling a live queue.
The MCP agent guide is useful if an AI model classifies or drafts items. Keep model proposals behind the same deterministic mapper and approval policy; the model should not receive tracker credentials directly.
Frequently asked questions
Does Relay provide built-in Jira, Linear, or GitHub integrations?
No built-in tracker integration is assumed here. Your adapter uses Relay REST for mailbox access and each tracker's official API for issue creation, with your own mapping, credentials, and recovery logic.
Should every inbound email create a new task?
Usually not. Apply routing and approval rules, suppress known automated noise, and define an update policy for related messages. A review queue is safer for ambiguous or privileged requests.
What is the safest deduplication key?
Use the Relay inbox ID and message ID as the source identity, protected by a unique constraint. Add tracker reconciliation for uncertain create responses, and use content hashes only as supporting evidence.
Connect mail to work without surrendering control
A neutral work item, durable source identity, explicit field mapping, and least-privilege tracker credentials make email-to-task automation maintainable across Jira, Linear, and GitHub. Start with one inbox and one test project, prove timeout reconciliation, then add routing rules and approvals where risk requires them. Relay supplies the temporary inbox and REST access layer; your adapter controls everything downstream. Review the Relay documentation and build the smallest pipeline that creates one accurate, traceable task at a time.