Set up your email domain

Your hosted AgentOwl address can receive mail in its Inbox and send after you enable it on Overview. You can also send from an address on your own domain. That sending setup requires you to publish the DNS records shown in AgentOwl; you keep your domain and DNS provider. Receiving on your own domain is a separate choice.

For a hosted address, activate its Inbox first, then choose Enable sending in the Send email panel. AgentOwl prepares and checks the sender automatically. The panel shows Ready to send when setup is complete. You can compose a message there or create a key for your agent that is restricted to that exact address.

If you only want to send from a domain you own, follow the outgoing setup in step 2 and leave your existing MX records in place. Steps 1 and 2 also explain the separate receiving setup if you want AgentOwl to handle incoming mail on that domain.

1. Choose which mail we should handle

Choose the domain and addresses you want to use, such as assistant@example.com. If you already use Google Workspace, Microsoft 365, or another mailbox provider, review its existing MX records before changing DNS.

• Dedicated subdomain: use an address such as assistant@agents.example.com, keeping your existing root-domain mail service.
• Whole domain: point the domain's MX to AgentOwl after its intended receiving addresses have been configured.
• Selected existing addresses: discuss forwarding from your current provider while retaining its MX records.

MX records route mail for a domain, not individual addresses. Adding our MX alongside another provider's does not split mail by recipient. The hosted receiver accepts active, exact AgentOwl addresses only; a domain-wide SMTP catch-all is not available.

2. Activate receiving in your workspace

1. Create an SMTP email binding for the exact lowercase address in your workspace. Connect it through an unconditional route to an active inbox or webhook endpoint.
2. Open Overview and find Receiving status for that address. For a custom domain, publish the displayed _agentowl.<domain> TXT record with its full agentowl-verification=<binding_id>.<tenant_id> value. This proves control of the domain without changing where its mail is delivered.
3. Select Verify and activate now, or allow the five-minute automatic check to complete. AgentOwl activates the address only when the ownership record, unique address, and active destination all pass. The same screen shows the result. A deliberate deactivation prevents automatic reactivation until you activate the address again.
4. Before changing MX, confirm the address is active and perform a controlled SMTP recipient check or test through an existing route. Then publish the MX record in the table below and send an external message to confirm it appears in the intended AgentOwl inbox or webhook.

If verification fails, keep the existing MX. Confirm the TXT record is publicly visible, the binding has an active destination, and no other AgentOwl binding claims the address. AgentOwl leaves the binding pending or failed until it can safely activate it.

For outgoing mail from your own domain, enter it under Your own domain in the Send email panel and choose Prepare domain. Publish the displayed _agentowl-send.<domain> ownership TXT record, then choose Check record. Enter the exact Address to send from and choose Enable sending. AgentOwl will display the SPF, DKIM, and DMARC records to add at your DNS provider. Choose Check status until the domain and address show Ready to send. Contact support@agentowl.dev if setup cannot finish. Do not send DNS account passwords or SMTP passwords to support.

Existing operator-managed receiver routes

Older installations can retain exact addresses in sendmailrs recipient.address_routes. Those entries take precedence over dynamic lookup and should be removed only after the corresponding AgentOwl binding is active and dynamic recipient checks pass. Keep a configuration backup and confirm both recipient acceptance and a delivered message after removal. The operator CLI activation remains available for these legacy deployments.

3. Add the supplied DNS records

The Overview shows the exact ownership record for each binding. The table below describes the other record types; placeholders are not values to publish.

Only change MX after the receiving server is ready. Sending-only setup does not require moving your existing inbox MX. Copy the exact type, host/name, and complete value displayed for your sender; do not substitute the example names in this guide.

Cloudflare Email Routing is not required for this hosted SMTP setup, even if Cloudflare hosts your DNS.

4. Configure sending

The AgentOwl send API keeps the mail-server credential on the server. Once the panel reports Ready to send, use Compose email or a key created under Connect an agent to send email. The key is restricted to one workspace and one exact From address. A hosted AgentOwl address needs an active Inbox before sending can be enabled. For a custom domain, confirm where replies to the exact From address will arrive. The API accepts one recipient per request:

POST /v1/email/send
Idempotency-Key: unique-request-key-123
Content-Type: application/json

{"tenant_id":"your-workspace-id","from":"hello@your-workspace.agentowl.dev","to":"you@example.com","subject":"Hello","text":"A test message"}

The caller needs an authenticated AgentOwl session or API credential with email:send scope. Outbound sending currently requires reviewed pilot enablement. Once enabled, setup activates the workspace when the exact sender is ready. A paused or suspended account cannot submit new mail. Repeat the same idempotency key and body to inspect a prior submission without submitting it again. The response contains a send_id and either accepted (the relay accepted the message) or uncertain (the relay outcome needs review). GET /v1/email/sends/<send_id> shows the stored status. Enabled Free accounts have a limit of 10 recipient submissions per UTC day; every account can submit at most five new recipients in a rolling minute. A complaint automatically suspends further sending until review. The API returns specific errors for pending approval, suspension, burst and daily limits, and suppressed recipients.

For existing operator-managed direct SMTP integrations, the server settings are:

Keep direct SMTP credentials in your application's secret store. Do not reuse another tenant's credentials. Receiving mail in AgentOwl does not provide IMAP or POP3 access, and inbound webhook configuration is not an outbound sending API.

5. Verify receiving and sending separately

Check receiving and outgoing mail separately:

1. Send an external message to your configured address and confirm it appears in the correct AgentOwl workspace and destination.
2. Use the guarded Sending panel or an authorized SMTP integration and inspect the received message's SPF, DKIM, and DMARC results, plus Inbox or Spam placement.
3. Reply to the outgoing message and confirm the reply reaches your AgentOwl inbox or webhook.

A server accepting a recipient does not prove that a message reached the inbox. Passing SPF, DKIM, and DMARC does not guarantee inbox placement. Record receiving and sending readiness separately and investigate spam placement before relying on production delivery.

Existing verified setup

Open Source Robotics uses this architecture: Kumo for outbound sending and sendmailrs for inbound custom-domain mail. Its older exact recipient mapping remains supported. New inbound addresses use AgentOwl's active binding lookup.

For incoming event fields and limits, see Email. For signing incoming webhooks, see Event format.