An agent that can read email can complete useful work: confirm a test account, inspect an attachment, or follow a signup flow. It can also expose private messages, create more resources than expected, or mistake a hostile email for an instruction. Giving every agent one powerful API key turns a helpful integration into an avoidable security problem.
Safe delegation starts with a simple question: what is the smallest email capability this agent needs, for how long, and at what cost? Relay provides scoped, revocable API keys and account-bound inboxes. Your own policy layer can add per-agent budgets, approval rules, and audit context. The combination is much stronger than a prompt that merely asks the agent to behave.
Treat every inbox as a security boundary
Do not let agents share a general-purpose mailbox by default. A shared inbox mixes test runs, customers, and workflows, making it easy for one task to read another task’s verification code. It also makes audit records difficult to interpret because every action appears to belong to the same identity.
Create a distinct inbox for each agent task or test run through POST https://www.relaymcp.net/api/v1/inboxes. For a longer-running agent, use a stable inbox dedicated to that agent and environment. Production, staging, and local testing should never share credentials or addresses.
Choose mail domains deliberately. Relay offers inboxes on separate Free mail domains and on verified user-owned domains; relaymcp.net is the website and never issues mailboxes. GET /domains lists available domains, while the domain documentation explains ownership and setup. A dedicated BYOD domain can separate agent traffic from other mail, but domain separation does not replace key scoping.
Most importantly, treat received email as untrusted data. Relay sanitizes HTML, yet sanitized content can still contain misleading instructions. An agent should extract facts from a message, not obey links, attachments, or requests found inside it without a separate policy decision.
Separate Relay controls from your policy layer
A useful permissions design distinguishes controls available in Relay today from controls your application should enforce. Do not assume that a prompt, an MCP client, or a naming convention creates a security boundary.
| Control | Relay currently supports | Where to add the rest |
|---|---|---|
| Authentication | Bearer API keys tied to one account | Separate key issuance per agent |
| Authorization | API key scopes and revocation | Tool allowlists and task-level approval |
| Resource access | Inboxes belonging to the issuing account | One inbox per task or workflow |
| Message reading | Preview list and full-message endpoints | Sender, age, and template filters |
| Credential lifetime | Scoped, revocable API keys | End access when the integration no longer needs it |
| Usage governance | Scoped identities that make activity attributable | Quotas, rate budgets, and cost ceilings |
| Investigation | Stable inbox, message, and key identifiers | Central audit events and retention policy |
Use scopes as the first filter
Issue keys from the account page, then grant only the scopes required for the workflow. A reader needs message and inbox read access, not inbox creation. A test runner that creates an inbox also needs write access. Revoke a key when the agent, environment, or owner changes.
Scopes are necessary but not sufficient. A key with inbox write access does not express “create at most three inboxes per run.” That is an application budget, so enforce it before calling Relay.
Constrain MCP tools as well
The Relay MCP endpoint exposes list_domains, list_inboxes, create_inbox, list_messages, and read_message. Give an agent only the tools its task requires. Keep routine verification read-focused after provisioning, and review retention guidance separately from the tools an agent uses to inspect mail.
MCP tool annotations help clients describe risk, but they are not a substitute for server-side scopes, account isolation, or your approval layer.
Give each agent a traceable identity
A practical identity record can be small: agent name, environment, owning service, Relay key identifier, allowed domain, and maximum inbox count. Store the API key in a secret manager as process.env.RELAY_API_KEY; never place it in prompts, source control, traces, or email content.
For example, a release-verification agent might receive read and write scopes, permission to use one test domain, and a budget of two inboxes per deployment. A support-triage agent might receive a different key with read-only access to its own account’s inboxes and no creation capability.
Avoid sharing one key across a fleet just because every instance runs the same code. Separate identities let you revoke a compromised worker without stopping unrelated jobs. They also make it possible to answer “which agent read this message?” without inferring the answer from timestamps.
If several agents need similar privileges, derive their configuration from the same policy template rather than reusing the credential itself. The policy is reusable; the identity should remain unique.
Enforce budgets before the agent calls Relay
Budgets belong in trusted code between the agent and the API. A model can propose create_inbox; your gateway decides whether the operation fits the run’s limits.
A minimal wrapper can maintain counters in the run’s durable state and reject excess calls:
const limit = 2;
const used = await store.countInboxes(runId);
if (used >= limit) throw new Error("Inbox budget exhausted");
const response = await fetch("https://www.relaymcp.net/api/v1/inboxes", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RELAY_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({})
});
if (!response.ok) throw new Error(`Inbox creation failed: ${response.status}`);
const { inbox } = await response.json();
await store.recordInbox(runId, inbox.id);
Persist the reservation before exposing the address to the agent when concurrent calls are possible. Otherwise two workers can both observe remaining capacity and exceed the budget. Add limits for message reads, attachment downloads, run duration, and concurrent tasks where those resources matter.
This is a team-implemented pattern, not a claim that Relay currently provides per-agent quota settings. The REST API reference supplies the operations; your gateway supplies the business rules.
Audit decisions without collecting sensitive mail
Record security events as structured metadata: run ID, agent identity, key identifier, action, inbox ID, response status, and timestamp. Include the policy result and the reason for denials. These records make budget tuning and incident response possible.
Do not copy authorization headers, full message bodies, verification codes, or attachments into routine logs. If debugging requires message details, use a separately controlled diagnostic process with a short retention period. A log entry such as read_message allowed inbox=… status=200 is usually more useful than a large, sensitive transcript.
Review denied actions as well as successful ones. Repeated attempts to create inboxes after a budget is exhausted may indicate a loop. Attempts to read an unrelated inbox may reveal a confused-deputy bug or an instruction-injection attempt. Alerts should point to the run and policy decision, not expose the email itself.
For automated test suites, apply the same identity and audit model in CI. The GitHub Actions email testing guide shows how to keep credentials and derived secrets out of workflow output.
Frequently asked questions
Does Relay provide built-in per-agent spending quotas?
Relay provides scoped, revocable API keys and account-bound inbox access. Per-agent inbox limits, read budgets, and approval thresholds are policies you should implement in your own gateway or job runner.
How should an autonomous agent handle inbox lifecycle?
Separate message reading from lifecycle planning. Relay inboxes have no fixed expiry, and switching addresses does not remove existing mail. Use task-specific access, review the privacy policy, and contact support for data-handling questions.
Is a dedicated inbox enough to make email instructions safe?
No. Isolation limits which messages an agent can access, but it does not make those messages trustworthy. Extract only expected data, validate sender and timing where relevant, and require separate authorization for consequential actions.
Conclusion: delegate tasks, not unlimited authority
Start with a unique agent identity, the narrowest Relay scopes, and an inbox dedicated to the task. Add durable budgets, tool allowlists, and metadata-only audits in code the model cannot bypass. Then test revocation and denial paths before expanding access. Relay gives you the email primitives; a deliberate permission layer turns them into safe, reviewable delegation.