Assign an inbox to an agent without sharing your mailbox

Start with a durable address

Give each independently accountable workflow a dedicated inbox, then store its inbox_id alongside your own agent identity. An email address is how other people reach the workflow; the inbox ID is how your application addresses its API resource. Keeping both avoids a fragile lookup by display name whenever a worker restarts. A support triage agent and a purchasing assistant usually deserve different inboxes because their allowed recipients, review policies and incident histories differ. Separate inboxes also let you disable one workflow without replacing the address used by every other agent in the workspace.

Choose the right creation path

Autonomous registration already returns a default project, inbox, assigned email address and restricted key. Use that returned inbox first. The bootstrap key cannot create additional inboxes or mint child keys, even though the Free workspace has an inbox allowance. An authorized owner credential can create an inbox through POST /v0/emails/inboxes. Supply a stable client_id derived from your internal workflow identity so an interrupted provisioning job can repeat the same creation request. The username is optional, while a custom domain must already belong to the workspace and pass verification.

Record ownership before delegation

Persist organization_id, project_id, inbox_id and the returned address as one provisioning record. Add a human-readable purpose and your own lifecycle state, such as provisioning, active or retired. Do not treat inbox metadata as an authorization policy: metadata helps operators find resources, while API-key scope and permissions enforce access. A workspace key can span multiple projects; a project or inbox key narrows which resources an agent can reach. Ask an owner to issue the appropriate credential rather than placing a broad owner key into every worker process.

Verify access with a read

Read GET /v0/emails/inboxes/:inbox_id using the credential that the actual agent will use. A successful provisioning call made with an owner key does not prove that the worker key has access. Compare the returned project_id and address with your saved record before accepting inbound work. Treat a 401 as a credential problem, a 403 as a missing permission, and a 404 as either an unavailable resource or a scope boundary. Do not work around a failed access check by silently switching the agent to a broader credential.

curl --fail-with-body "https://api.lupin.sh/v0/emails/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $LUPIN_API_KEY"

Retire an inbox deliberately

Deleting an inbox cascades into its messages and threads, so address retirement belongs in an explicit operations workflow. Stop new jobs, revoke delegated access and decide what records your organization needs before deletion. Consider leaving an inactive inbox available for a bounded transition if external senders still use its address. Receiving email does not grant permission to send replies, purchase resources or operate another customer account. Your next step is to save the provisioning mapping and perform a read with the delegated key, then build the inbound processor around that stable inbox identity.

Check the returned identity

For example, a worker assigned to the support project should compare the inbox response’s project_id with its saved support project before accepting a job. A display_name of Support is not sufficient because another project may use the same name. Keep this identity assertion at the client boundary so later routing changes cannot silently cross customer contexts.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin inboxes ↗Checked 2026-11-05
• Lupin API keys ↗Checked 2026-11-05
• Lupin agent registration ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.