API keys

Open Settings → API keys. A key acts as its creator within the selected organization and cannot bypass that user’s mailbox access or role.

Create a key

1. Give it a recognizable name, such as “Reporting script”.
2. Select only the permissions it needs. Start read-only.
3. Set a send limit if sending is enabled, and choose an expiry.
4. Create and copy the key immediately. It is shown only once.

Use a separate key per tool. Store it in that tool’s secret storage or environment, never in a public repository or chat message.

Permissions

Scopes do not grant extra mailbox access. Sending stays within your plan's sending limits.

Create a project key through your agent

A hosted OAuth agent can use create_project_key after an owner/admin explicitly approves the additional keys:write permission and mail:send. This permission is never included in a scope-less connection. Existing API keys cannot mint other keys, and the manual key form does not grant key-management permission.

The project tool creates a named send-only key, with a default 90-day expiry and a daily limit no higher than the issuing connection's. It returns MAILMOOSE_API_URL, MAILMOOSE_API_KEY and MAILMOOSE_FROM once. The sender value configures the app; it is not a sender restriction on the credential. The key still acts as its creator and inherits that person's accessible mailboxes. Revoke the app key separately even if you disconnect the agent.

The secret is present in the agent's MCP tool result. Do not echo it in chat or logs. A trusted coding agent can write it to an ignored .env.local; a hosted chat without file access cannot. See agent setup for the complete flow.

Limits that protect you

The creation form defaults sending keys to a 100-message rolling 24-hour safety limit. All sending also counts toward the shared account allowance: 500 recipients per rolling 30 days on paid plans. Adding keys never adds sending capacity. View your current usage in Settings → Billing → Monthly sending. Sending limits.

The expiry selector defaults to 90 days and also offers 30 days, one year or no expiry. Prefer an expiry you can rotate reliably.

See sending limits.

Revoke a key

Use the revoke control beside the key. Revocation stops future authentication; it does not undo email already sent. If exposed, revoke immediately and create a replacement.

Hosted OAuth agent connections have their own tokens and do not require copying one of these keys. Disconnect those in the client that created the connection.

See using the API.