# One API for your agent’s email conversations.

Create mailboxes, send messages, receive replies and load conversation history. Connect email to your agent without running a mail server.

REST, SDKs and MCP. API-key authentication. Your application stays in control.

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

## Build around a mailbox

A send endpoint is one part of an agent workflow. Once the recipient replies, your application needs to know which agent owns the address, which conversation the reply belongs to and what has already happened.

Robotomail's API is organized around mailboxes, messages and threads. Provision an address, send from it and receive replies into that same mailbox. Use API keys with the access the integration needs, rather than putting credentials into model-generated text.

The public API base is `https://api.robotomail.com/v1`. Authenticate with an `Authorization: Bearer` header. Keep the key on your server. The [authentication reference](/docs/authentication) explains key scopes and handling.

## Send your first message

Verify your account, then list your mailboxes to obtain a mailbox ID. Send a message with `bodyText`; optionally include an HTML version with `bodyHtml`.

```bash
curl https://api.robotomail.com/v1/mailboxes \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY"

curl -X POST https://api.robotomail.com/v1/mailboxes/MAILBOX_ID/messages \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["recipient@example.com"],"subject":"Your request","bodyText":"I have received your request. Reply here with any extra details."}'
```

Replace `MAILBOX_ID` with the ID returned by your account. Use a recipient you control for the first test. Store the returned message ID and inspect delivery events; acceptance of the send request is not proof of inbox placement.

For full request and response fields, use the [messages reference](/docs/api/messages). Prefer a tested example in the [first-send guide](/docs/guides/send-first-email) before connecting model-generated content.

## Close the loop when someone replies

Register a webhook for `message.received`, listen to [server-sent events](/docs/api/events) or poll the mailbox's messages. A webhook can wake your application; the message and thread APIs provide the context it needs to respond.

When replying, use the original email's RFC Message-ID in `inReplyTo`. This is different from Robotomail's database ID for the message. Send from the appropriate mailbox, preserve the subject where useful and explicitly check the recipients.

Treat webhook deliveries as notifications that may be retried. Verify the HMAC signature over the raw body before parsing and record processed events or message IDs so your workflow does not repeat a side effect. See [receive and reply](/docs/guides/receive-and-reply) for a complete implementation path.

## Keep the files and context together

Outgoing attachments use an upload flow: upload the file to the attachments endpoint, then include the returned attachment IDs in the send request. Message results expose attachment metadata; retrieve an attachment to obtain a fresh download URL when needed.

For conversation context, fetch the relevant thread rather than feeding an agent the whole mailbox. Page through message lists and keep only the history needed for the task. Filter sent-message retrieval with `direction=OUTBOUND` when you need to audit what the agent has already sent.

Check [attachments](/docs/concepts/attachments), [threads](/docs/api/threads) and [limits](/docs/concepts/limits) when sizing a workflow. Storage is measured at account level; it is separate from monthly sends and inbound usage. See [plans and allowances](/pricing) when choosing capacity for a production workflow.

## Transactional email with a reply path

A receipt, activation message or account notice can start a useful conversation. Send it from a mailbox your application monitors so a customer can reply when something goes wrong.

Your application creates the business event, renders the message and controls recipients. For activation emails, it also creates and validates the token, sets expiry and rate-limits resend requests. Robotomail sends the resulting email; it does not issue your application's activation tokens.

Keep sensitive tokens out of analytics and general logs. Do not reveal whether an account exists through the wording or timing of a resend endpoint. The [SaaS onboarding example](/use-cases/saas-onboarding#activation-emails) explains how to connect outbound onboarding with inbound help.

## Email notifications your users can answer

Use an application event to trigger an email through the messages API. Store the event-to-message relationship so you can reconcile retries, delivery outcomes and responses.

Your application owns notification preferences, scheduling, digesting, cancellation and any cross-channel orchestration. Check those preferences before sending. Add rate limits for noisy events and give users a clear way to stop optional notifications.

Robotomail supplies email transport and the mailbox where a reply arrives. The [inbound email API](/inbound-email-api) turns that reply into an event your application can process.

## Email infrastructure you do not have to operate

Operating a mail server involves inbound routing, outbound delivery, DNS, queues, storage, abuse handling and ongoing maintenance. A managed mailbox API lets your team spend its effort on the workflow that makes the email useful.

Robotomail provides managed mailboxes and an HTTP API. You still own application availability, safe agent behavior, webhook processing and the DNS changes for a custom domain. Plan limits, recipient behavior and mail-provider filtering still apply.

Before rollout, verify sender identity, run a send-and-reply test, monitor bounces and make a recovery plan for failed requests. See [delivery operations](/docs/guides/email-delivery).

## Moving from SMTP configuration to an API

An SMTP integration asks for a host, port, transport security and an SMTP username and password. Robotomail's documented sending interface uses HTTPS and a bearer API key. Do not place that key into an SMTP password field or assume there is an interchangeable SMTP host.

To migrate, identify where your application currently sends mail, replace that call with the messages endpoint and map sender identities to Robotomail mailboxes. Keep plain text, HTML and attachment handling explicit. Test failure responses and delivery events before moving production traffic.

If your existing software only accepts SMTP settings, it needs an HTTP-capable adapter or an integration change. Review the [API reference](/docs/api/messages) and [language SDKs](/docs/sdks) before choosing the implementation.

## Common questions

### Can I both send and receive through the API?

Yes. Send from a mailbox, retrieve messages and threads, and connect inbound webhooks, the event stream or polling to your application.

### Is an API key the same as an SMTP password?

No. Use the API key in the Authorization header of an HTTPS API request. The documented integration does not provide SMTP settings for existing SMTP-only clients.

### Does a successful send mean the email was read?

No. A send result and a delivery event report different stages. Delivery means the receiving server accepted the message; it does not prove inbox placement or a human read.

### Where can I check limits and prices?

Use the current pricing page for plans and the limits reference for how quotas and storage are applied. Size your workflow around both inbound and outbound usage.

### 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

- [Receive email through the API](/inbound-email-api)

- [Python email tutorial](/blog/how-to-send-email-with-python)

- [JavaScript email tutorial](/blog/send-an-email-using-javascript)

- [PHP email tutorial](/blog/mail-php-sender)