Create Sara’s identity. Send a message. Read the reply.

Before you start

Access is coming soon. Request Access on the Agent Identities page. These examples are a preview for future account holders; they require an active domain with room for another mailbox.

Set MAILRUN_AGENT_API_URL to the API base URL supplied for your account, without a trailing slash, and MAILRUN_AGENT_KEY to your secret API key. The examples require agent:identities.write, agent:identities.read, agent:email.send, and agent:email.read scopes. Keep the key on your server or trusted local machine, never in browser code.

Use a real test recipient you control. The example.com addresses below are placeholders and must be replaced. The create and send requests change your account and send real email; the page itself runs nothing.

01 / Create an identity with email

Replace your-domain.example with your active domain and choose an unused local part. The daily cap of 1 keeps this test small. Save the returned id as IDENTITY_ID. A successful create returns HTTP 201; email provisioning continues in the background.

Choose one unique Idempotency-Key for this creation. If the response is lost, retry the same request with the same key and body. Use a new key only for a genuinely new identity.

curl "$MAILRUN_AGENT_API_URL/v1/identities" \
  -X POST \
  -H "Authorization: Bearer $MAILRUN_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sara-first-identity-001" \
  -d '{"name":"Sara","email_local_part":"sara","email_domain":"your-domain.example","domain_mode":"root","daily_send_cap":1}'

02 / Check that email is ready

Read the identity until status is active and email_address is populated with the intended address. An identity record alone is not proof that email is ready. If provisioning fails or the identity becomes suspended, resolve that state before sending.

curl "$MAILRUN_AGENT_API_URL/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $MAILRUN_AGENT_KEY"

03 / Send one introduction

Replace you@example.com with your test inbox. HTTP 202 means the send was accepted for processing, not that it reached the recipient. Save the returned message id and check message history for progress. Use the same send key and body if you need to retry after a lost response.

curl "$MAILRUN_AGENT_API_URL/v1/identities/$IDENTITY_ID/messages" \
  -X POST \
  -H "Authorization: Bearer $MAILRUN_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sara-first-message-001" \
  -d '{"to":["you@example.com"],"subject":"Hello from Sara","text":"This is our first Mailrun test. Please reply so we can verify both directions."}'

04 / Reply and read it back

Reply from your test inbox, then list inbound messages. The response contains data and next_cursor. Save the reply’s id as MESSAGE_ID and request that message to read its available body. An empty list means no matching inbound record is available yet; it does not prove the reply was received.

curl "$MAILRUN_AGENT_API_URL/v1/identities/$IDENTITY_ID/messages?direction=in" \
  -H "Authorization: Bearer $MAILRUN_AGENT_KEY"

curl "$MAILRUN_AGENT_API_URL/v1/identities/$IDENTITY_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILRUN_AGENT_KEY"

Next: connect the working agent

Once both directions work, connect the same identity to your agent’s HTTP integration or MCP client. Give the agent your business context and permissions. Raise the daily email cap deliberately when you are ready to expand the test.

For phone, provision a number and connect your hosted voice agent. Live inbound conversations require a public HTTPS voice handler; your application supplies the context and response. Our team can help you verify the first call.