Skip to navigation
Products & Surfaces

Setting up an email surface

Connect an email address to a Product with an Email Surface. Runtype routes each inbound email to your Product and sends the response as a reply in the same email thread.

Before you begin

Make sure that you have these items:

  • A Product.
  • The Capability that handles emails.
  • Optional: A Resend account with a verified sending domain, if you want replies to come from your own domain.

Create an Email Surface

Create the Email Surface and configure it in one pass:

  1. Open the Product that you want to connect to email.
  2. Open Surfaces and click Add Surface.
  3. Under Messaging Channels, select Email Channel. Runtype creates the Surface in Draft status and opens the Surface panel on the General tab.
  4. In Capability, select the Capability that you want to run.
  5. Click the Inbound tab. Copy the Inbound Email Address. This address ends in @runtype.email, and Runtype sends every email that arrives at it to this Surface.
  6. In Email Provider, keep Runtype Email to send replies without an API key, or select Resend to send them from your own domain. For the Resend settings, see Send replies from your own domain.
  7. Optional: Enter a From Name. Recipients see this name on each reply.
  8. Click Save Changes.

With Runtype Email, replies come from the inbound email address, so a reply from the sender returns to the same Surface.

For more information about Capabilities, see Adding capabilities to a Product.

Test the Surface in Draft

A Draft Email Surface accepts email only from the email address of the account that created the Product. Other senders get a bounce. Use this to test the Surface before other people can reach it:

  1. From your account’s email address, send an email to the inbound email address.
  2. In the Product, open Activity and confirm that a conversation from your email address appears.
  3. Confirm that a reply arrives in the same email thread.

Activate the Surface

To accept email from any sender, follow these steps:

  1. Open the Surface panel and click the General tab.
  2. In Status, select Active.
  3. Click Save Changes.

Paused and Archived Email Surfaces reject all inbound email.

Send replies from your own domain

Select Resend as the Email Provider to send replies through your own Resend account:

  1. On the Inbound tab, in Email Provider, select Resend.
  2. In API Key, enter a Resend API key.
  3. In From Address, enter an address on a domain that you verified in Resend, such as support@example.com.
  4. Click Save Changes.

Inbound email still arrives at the inbound email address. When a customer replies to your From Address, the reply reaches the Surface only if your mail system forwards it to the inbound email address.

Configure replies

The Outbound tab controls how the Surface replies. The following settings apply to Email Surfaces:

  • Auto Response: when this setting is on and Welcome Message has text, Runtype sends the welcome message as a separate email at the start of each new conversation. The Capability still replies to every email when this setting is off.
  • Welcome Message: the text of the first email in a new conversation.
  • Email Signature: text that Runtype adds to the end of the welcome message. Runtype doesn’t add it to Capability replies. To sign every reply, include the sign-off in the instructions of the Capability.
  • Reply format: select Markdown (recommended) to have the Capability write Markdown that Runtype renders as an HTML email. Select Raw HTML to have the Capability write the full HTML email. Runtype removes scripts and other unsafe content before it sends the email. Raw HTML uses more tokens.
  • Error Message: the reply that Runtype sends when the Capability fails.
  • Debug Mode: adds error details to the error reply. Turn it off before real users send email to the Surface.

How conversations and replies work

Each new email starts a conversation. A reply in the same email thread continues that conversation, so the Capability receives the earlier messages.

By default, a reply goes to the sender and keeps the other To and Cc recipients of the inbound email. Runtype removes the Surface’s own addresses from the recipients.

An Email Surface can’t collect tool approvals. When an attached Agent requires Tool approval, Runtype refuses the run, and no gated tool runs. For more information, see Approvals on messaging surfaces.

Troubleshoot the Surface

If an email bounces with Address not found, check these settings:

  • Status: set the Surface Status to Active. A Draft Surface accepts email only from the account that created the Product, and a Paused or Archived Surface accepts none.
  • Address: copy the address from Inbound Email Address and confirm that you sent the email to that exact address.

If an email doesn’t bounce but gets no reply, check these causes:

  • Automated sender: Runtype doesn’t reply to auto-replies, mailing lists, bulk mail, or senders such as no-reply and mailer-daemon. Send the test from a personal mailbox.
  • Message size: Runtype rejects an email larger than about 900 KB, including attachments.
  • Capability: select a Capability in the Surface panel and click Save Changes.
  • Errors: turn on Debug Mode on the Outbound tab, send the email again, and read the error details in the error reply.
  • Rejecting events: if the channel shows Rejecting events in the product editor, read the reason in the banner. Either the webhook secret doesn’t match the Surface, or, with Resend, Runtype couldn’t fetch the email content. For Resend, confirm that the API key has the Receive emails permission. For more information, see Inbound webhook rejected.

Next steps

Continue with these guides: