# Turn incoming email into your agent’s next action.

Receive email in a real mailbox. Get an event, read the message and thread, then let your application decide what happens next.

For support intake, lead replies, document processing and ongoing agent conversations.

[Create a mailbox](/sign-up) · [See plans](/pricing)

## Give every reply somewhere to go

An inbound email API turns an arriving message into data your application can use. Robotomail receives email at its mailboxes and makes the message, conversation and attachment metadata available through the API.

Your application can subscribe to a webhook, listen to the event stream or poll for new messages. It can then classify an inquiry, extract information, ask a follow-up question or create a task in another system.

The mailbox remains the address people reply to. Your code owns the business action, approval rules and integration with your CRM, ticketing system or agent runtime.

## Receive, understand, respond

1. **Choose the receiving address.** Use a Robotomail platform mailbox or configure a verified custom domain.
2. **Subscribe to incoming mail.** Register `message.received` for the mailbox or use the event stream or polling.
3. **Fetch the message.** Read the API's message data and load relevant thread history. Retrieve attachments only when the workflow needs them.
4. **Validate the requested action.** Treat both the email and files as untrusted input. Check the sender's authority before exposing private data or taking an irreversible action.
5. **Reply or hand off.** Send from the receiving mailbox with the correct `inReplyTo`, or route the request to a person in your own application.

This keeps the email interface consistent while you evolve the model or workflow behind it.

## Wake your application when a message arrives

Register a public HTTPS endpoint that your application controls:

```bash
curl -X POST https://api.robotomail.com/v1/webhooks \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example.com/hooks/email","events":["message.received"]}'
```

Store the returned webhook secret securely. Verify `X-Robotomail-Signature` against the raw request bytes before trusting the webhook as a Robotomail delivery. Signature verification does not make the email's contents trustworthy.

Acknowledge accepted notifications promptly and queue longer processing. Make processing idempotent so retries cannot create duplicate tickets or send duplicate replies. Keep an application-side record of the message and action outcome. Follow the [webhook reference](/docs/api/webhooks) for payload fields and retry behavior.

## Choose the right way to receive events

**Webhooks** fit a deployed service with a reachable endpoint. They let incoming messages initiate work without a continual mailbox scan.

**Server-sent events** fit a running process that can keep a connection open. Use the documented event stream and reconnect behavior; keep your own processing checkpoint rather than assuming an unlimited event history.

**Polling** fits scheduled jobs or environments that cannot receive webhooks. List messages for a mailbox, paginate results and deduplicate by message ID. A timestamp filter helps narrow a scan, but your application's processing record determines what has actually been handled.

Choose the transport your runtime can operate reliably. See [events](/docs/api/events), [messages](/docs/api/messages) and [receive and reply](/docs/guides/receive-and-reply).

## Work with the message and its conversation

Use the parsed message fields for your application logic, and inspect the API schema before wiring a payload into a model. Do not assume a generic email provider's `text` or `html` field names match Robotomail's response.

Load the thread when a reply depends on earlier messages. Keep the Robotomail message ID for API retrieval and the RFC Message-ID for email reply headers; they serve different purposes.

Incoming attachments have metadata such as name and content type. Those values are supplied by the message and should not be treated as evidence that a file is safe. Fetch a fresh attachment download URL when needed, enforce size and type constraints in your application and isolate any file processing. See [attachments](/docs/concepts/attachments) and [agent email security](/docs/guides/agent-email-security#attachments).

## Use your own receiving domain carefully

MX records tell other mail servers where to deliver email for a domain. They are different from the API URL your application calls to read messages.

If your main domain already receives employee mail, a dedicated subdomain can give agents their own routing without changing the parent domain's MX records. Publish exactly the records returned during custom-domain setup, verify them and create the intended mailbox addresses.

Changing a domain's MX records moves its inbound delivery route. It does not import old messages or automatically preserve delivery at the previous provider. Plan a cutover, test from an external mailbox and verify the reply path. Follow [custom domain setup](/docs/guides/custom-domain).

## Keep the inbox connected to useful work

Test a message, a reply, a duplicate event and a processing failure before automating a whole inbox. Store task state outside the model so a restarted worker can recover safely.

Monitor inbound volume, storage and processing latency. If a message appears missing, check the mailbox address, domain verification, DNS routing, API key scope and plan limits before assuming the message was never received. Over-limit visibility and counters need to be interpreted using the [limits documentation](/docs/concepts/limits). Check [plans and inbound allowances](/pricing) before choosing capacity for a production workflow.

For support or lead intake, add a human handoff when the agent is uncertain. For documents and account actions, validate permissions in your application even when the email appears to come from a known sender.

## Common questions

### Does this read an existing Gmail or Outlook inbox?

The inbound API reads Robotomail mailboxes. It does not automatically connect to a different provider or import that provider’s mailbox history.

### Do I need a custom domain to start?

You can start with a platform mailbox. Add and verify your own domain on a paid plan when the workflow needs that identity.

### Can an incoming email create a support ticket?

Yes, your application can use an inbound event to create or update a ticket in your own system. Robotomail provides the mailbox and email data; your application owns the ticket state and routing.

### Can the agent respond automatically?

Your application can send a reply after processing the email. Define recipient checks, permission checks and human approval rules before enabling automatic actions.

### What's included in the Free plan?

1 mailbox, 10 sends and 10 receives per month, only between your agent and your verified email address. No credit card, no expiry. Allowances reset on the first of each month (UTC). Upgrade to email other people or use a custom domain.

## Continue building

- [Build an email support workflow](/use-cases/customer-support)

- [Set up receiving and replies](/docs/guides/receive-and-reply)

- [Send email through the same API](/email-api-for-ai-agents)