# Email Ingest

Every webhook can receive inbound email through its generated address, which makes email another source channel that ends in normal delivery history, replay, and DLQ handling. Use this when the producer is a mailbox or vendor that can only send email.

## Email channel model

Email ingest uses the webhook's `emailIngestAddress`, which is returned on webhook create and follows this shape:

```text
hook_xxx@ingest.hooksbase.com
```

The address itself is the primary access credential — rotate the webhook if it leaks. An empty sender allowlist means **open ingest**: any sender who knows the address is accepted. Add allowlist entries to narrow that down.

Delivery-state behavior is intentionally quiet:

- archived or missing webhooks reject as unknown recipient
- paused webhooks are silently accepted at the SMTP layer but skipped
- disabled projects are silently dropped to avoid bounce loops
- blocked senders are silently dropped instead of bounced

## Auth model

- **Source channel**: There is no public HTTP email-ingest route. The producer sends mail to the webhook's generated address.
- **Public API** `project API key`: Manage sender allowlists through the webhook email-allowlist routes.
- **Dashboard** `session auth`: The [dashboard](/docs/dashboard.md) lets you add and remove allowlist entries from the webhook's email settings tab.
- **SDK / CLI**: There is no first-party email-ingest helper in the SDK or CLI yet.

## Sender allowlists

Allowlist entries are per-webhook and support:

- exact addresses such as `alerts@example.com`
- domain wildcards such as `*@example.com` or `example.com`
- local-part wildcards such as `monitoring@*`

An empty allowlist keeps the channel open. Duplicate patterns return `409`. Listing allowlist entries is available with a project key; creating or deleting entries requires Starter+.

If email provider configuration changes later, a previously skipped invitation or alert email can start delivering, but inbound allowlist rules are still enforced by the webhook's own configuration.

## Payloads and attachments

Hooksbase parses the raw message into a JSON envelope with fields such as:

- `from`
- `to`
- `subject`
- `messageId`
- `date`
- `text`
- `html`
- selected forwarded headers
- `attachments`

Attachment behavior matches the file-storage model:

- per-file limit: `15 MB`
- per-ingest total: `50 MB`
- when the project has file storage quota, attachments are uploaded and exposed as `fileRef` entries
- free-tier projects keep attachment metadata only
- oversized email attachments are not bounced; if attachment upload cannot fit the per-file or per-ingest limits, the delivery keeps metadata instead of a `fileRef`

For the broader download and retention model, see [files](/docs/files.md).

## Related routes

- `GET /v1/webhooks/{id}/email-allowlist`
- `POST /v1/webhooks/{id}/email-allowlist`
- `DELETE /v1/webhooks/{id}/email-allowlist/{entryId}`

## Common mistakes

- Treating the email address as a permanent public identifier you can safely publish widely.
- Assuming an empty allowlist means email ingest is disabled. It means open ingest.
- Expecting blocked senders or paused webhooks to produce SMTP bounces.
- Forgetting that attachment persistence depends on project file-storage quota.