# Sending email

Most apps that do anything for real eventually need to send email: a confirmation when someone
signs up, a receipt after a purchase, a "click here to reset your password" link. onvibe ships
this in: every project gets its own email-sending identity the moment you create it. Your AI
just calls a `sendEmail()` function from your app's code and the platform takes care of the rest.

## How it works in plain terms

When you create a project, the platform sets up a **dedicated sending address** for it under
`{project-name}.email.onvibe.run`. So if your project is called `bookclub`, your app sends from
something like `noreply@bookclub.email.onvibe.run`. Each project has its own DKIM signature, so a
problem with one project's email never drags down the others.

The default sender is fine for most cases — friendly enough to use, plain enough that recipients
recognize it as automated.

## Asking your AI to send email

You don't need to remember the API. Talk like you would to a person:

> *"When a visitor RSVPs yes, send me an email with their name and the message they left."*

> *"Add a 'forgot password?' flow that emails the user a reset link valid for one hour."*

> *"Once a day, email me a summary of the new orders that came in."*

Your AI wires the call to `sendEmail()` in your app code, redeploys, and the next event triggers
the email.

## What you can send

Each email needs three things: who it goes to, a subject line, and a body. The body can be HTML
(so you can style it) or plain text, or both — your AI will pick. Optionally you can also add
Cc, Bcc, a Reply-To address, or override the sender display name (e.g. `"My App <hello@my-app.email.onvibe.run>"`).

## Limits during the free beta

While we're in beta, every project has a small budget so a runaway loop or a misuse can't burn
through your sending reputation:

- **5 emails per hour**
- **10 per day**
- **100 per month**
- Up to **5 recipients per message** (To + Cc + Bcc combined)

If you go over, the call fails with a clear error and the platform suggests waiting or splitting
the message. The quota resets on the next hour/day/month boundary.

## Testing it

Ask your AI:

> *"Send a test email to me at your-email@example.com from the bookclub project."*

The first time you do this on a brand-new project, the platform may take a minute or two to
confirm the new sending identity with the email infrastructure (DKIM verification). If you see
an `EMAIL_IDENTITY_PENDING` error, wait a minute and ask again — it'll succeed once the
verification completes.

## Where this fits

This is for **outbound, transactional email** the app sends as it runs. It's not for:

- **Marketing campaigns / newsletters** — go through a dedicated provider for that; the per-project
  quotas here are tuned for transactional volume.
- **Receiving email** — onvibe doesn't accept inbound mail at the moment.
- **Platform notifications** like password reset for your onvibe account — those come from a
  separate system address (`noreply@onvibe.run`) and don't count against your project quota.

## Good to know

- The first email from any new project lands a minute later than usual the first time, while
  the sending identity finishes verifying. After that it's instant.
- If you ever see a recipient's mail provider flagging the email as spam, ask your AI to look at
  the message body — the most common cause is content that triggers spam filters (lots of links,
  suspicious wording), not the platform itself.
- The platform keeps an audit log of every send for the last 90 days. If you suspect a problem
  ("did my receipts go out yesterday?"), ask your AI to check.