Agent Mail quickstart: create an inbox and send email

Before you start

You need an Outflare account, a workspace and a brand. Agent Mail is a paid module; check its availability and setup status inside Outflare before testing real delivery. A custom domain is optional.

The examples below use environment variables as placeholders. Set them locally or in a server-side secret store. Never put a key in a public repository or client-side application.

1. Create an inbox in Outflare

Open Agent Mail in your workspace and select a brand. Create an inbox with a chosen name or a generated name. Start with the platform domain agentsget.email, or select a custom domain you have already verified.

Copy the brand and inbox identifiers from the dashboard. An inbox is persistent: later messages and replies remain associated with that inbox until deletion or the service’s retention rules apply.

2. Create a scoped key

Select the inbox, then create an Agent Mail key with read permission. Add send if your test will send or reply. Copy the key when it is shown; its secret is not shown again later.

Set BRAND_ID, INBOX_ID and AGENT_MAIL_KEY in your shell. Use a key restricted to this test inbox rather than a credential that can administer your workspace.

3. Read the inbox

curl --get \
  "https://app.outflare.ai/v1/cloud/agent-mail/brands/$BRAND_ID/inboxes/$INBOX_ID/messages" \
  --header "Authorization: Bearer $AGENT_MAIL_KEY"

A new inbox may be empty. Send a controlled test email to its address, then read the inbox again. Follow the response cursor to retrieve additional pages rather than assuming one response contains all messages.

4. Send a controlled test message

Replace [email protected] with an address you control. Use a fresh idempotency key for each distinct message; reuse the same key only when retrying the identical request.

curl --request POST \
  "https://app.outflare.ai/v1/cloud/agent-mail/brands/$BRAND_ID/inboxes/$INBOX_ID/messages" \
  --header "Authorization: Bearer $AGENT_MAIL_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: quickstart-message-001" \
  --data '{
    "to": ["[email protected]"],
    "subject": "Hello from my agent inbox",
    "text": "This is a controlled test message."
  }'

Acceptance into the send queue is not a delivery guarantee. Inspect the message status and delivery feedback. If the outcome is unknown, investigate the original message rather than sending it again with a new key.

5. Add the next part of your workflow

Reply from your test recipient and confirm that the incoming message appears in the inbox. Then add a receiving webhook, connect an MCP-compatible client, or follow the custom domain guide.

If a request is rejected, first check that the key includes the selected inbox and required read/send permission, then check the module’s status in Outflare. Use the error code and request identifier when investigating a failed request.

Prefer runnable source files? Try the tested Python starters.