> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parser-app.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deals from email

> Forward a deals inbox, or connect Gmail, Microsoft 365 or IMAP. Each deal thread becomes one job.

Connect a mailbox with `POST /v1/mailboxes` (`mailboxes:manage`). Every message that arrives is read as a
submission, and **a deal thread ends in one job**:

* A message with attachments starts a job with every document its thread has sent so far.
* A reply that adds documents (the missing statement) starts a new job with the thread's documents plus its
  own; the earlier job's `superseded_by` names it. Earlier reads are reused, so only the new files cost anything.
* A forward whose documents the thread already holds returns the thread's job (`merged`).
* A message with no document (a question, a thank-you) starts none.

Every message is also a [tracked email](/guides/emails), with a stable `email_id`: its envelope, what became of
it, its raw `.eml` and your tags, and its whole thread. `GET /v1/mailboxes/{id}/messages` lists what became of each
message (`job`, `merged`, `ignored:<reason>` or `refused`) with its `email_id`, without its subject or body.
`PATCH` a mailbox to pause it: its mail is then `refused`, tracked by its envelope only.

Two mailbox settings shape the tracking: `store_raw_email` (on by default) keeps each message's raw `.eml`, and
`default_tags` tags every email the mailbox receives, e.g. `["client:lifetime"]`. See
[Emails and threads](/guides/emails).

## Kinds of mailbox

<Tabs>
  <Tab title="Forwarding address">
    Works with any mail system. `POST /v1/mailboxes` with `{"kind": "forwarding"}` answers a private address,
    `<token>@in.parser-app.com`. Forward your deals inbox to it with a Gmail filter or an Outlook rule. Mail to an
    unknown address bounces.

    Gmail first sends a confirmation code to a new forwarding address. It starts no job, and
    `GET /v1/mailboxes/{id}/verification` shows the code and link so you can confirm it.

    Anyone who learns the address can mail it, so:

    * **Allowed senders**: `PATCH /v1/mailboxes/{id}` with `{"settings": {"allowed_sender_domains": ["funder.com"]}}`
      takes only mail forwarded from those domains (and their subdomains), judged by the envelope sender: the
      mail system that forwards, not the ISO in `From`. A Gmail filter or Outlook rule of `deals@funder.com`
      keeps `funder.com` there. Other mail is `ignored:sender_not_allowed`.
    * **Hourly cap**: a mailbox takes 300 pushed messages an hour. Beyond that, mail is held and delivered later,
      never lost.
    * **Rotation**: `POST /v1/mailboxes/{id}/rotate-address` gives the mailbox a new address. The old one
      bounces from then on, and Gmail asks you to confirm the new one.
  </Tab>

  <Tab title="Gmail (Workspace)">
    `{"kind": "gmail", "auth": "delegation", "address": "deals@funder.com"}`. Your Workspace super-admin authorizes
    our service account once, for `https://www.googleapis.com/auth/gmail.readonly`, under **Security → API
    controls → Domain-wide delegation** (we give you its client ID). Only the addresses you register as mailboxes
    are read, and each connection is audited.

    New mail is announced by push and read within seconds. `label` reads only messages with that label (`INBOX`,
    or one a filter applies).
  </Tab>

  <Tab title="Microsoft 365">
    `{"kind": "m365", "address": "deals@funder.com", "organization": "<your Microsoft tenant id or domain>"}`.
    The answer's `authorize_url` is an admin-consent link for our app (application permission `Mail.Read`). You can
    restrict it to the registered mailboxes with an Exchange application access policy. New mail is announced by
    Microsoft Graph and read within seconds.
  </Tab>

  <Tab title="IMAP">
    `{"kind": "imap", "address": "...", "imap": {"host": "...", "port": 993, "username": "...", "password": "...", "folder": "INBOX"}}`.
    Works with any mail server. The login is checked and stored encrypted. Messages are read without being marked
    read, and IMAP IDLE picks up new mail as it arrives.
  </Tab>
</Tabs>

Mail already in a mailbox when it is connected is not parsed. `POST /v1/mailboxes/{id}/resync?since=` reads up
to 7 days back. A mailbox whose credential is revoked becomes `reauth_required` and emits `mailbox.disconnected`.

## A provider posting mail itself

A forwarding mailbox also comes with an `inbound_secret`, shown once at creation, so a mail provider can post
raw messages for that mailbox to `POST /v1/intake/email`:

```bash theme={null}
# X-Signature = hex HMAC-SHA256("<ts>\n<mailbox id>\n<message id>\n<body>") with the mailbox's inbound secret
TS=$(date +%s); MSG=provider-message-123
SIG=$( { printf '%s\n%s\n%s\n' "$TS" "$MAILBOX_ID" "$MSG"; cat deal.eml; } | openssl dgst -sha256 -hmac "$INBOUND_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST "$API/v1/intake/email" -H "Content-Type: message/rfc822" -H "X-Timestamp: $TS" \
     -H "X-Mailbox-ID: $MAILBOX_ID" -H "X-Provider-Message-ID: $MSG" -H "X-Signature: $SIG" --data-binary @deal.eml
```

With an API key instead (`jobs:write`), any raw email can be posted the same way, without a mailbox. Either way
the answer's `X-Email-ID` header names the tracked email, and posting the same message again is the same email
and the same job.

## Routing

With the `email_routing` module, each email is classified before it is parsed: `new_submission`,
`more_documents`, `question_or_update`, `internal_note`, `contract_or_funding` or `not_deal_related`. The answer
is on the job (`result.email.routing`) and on an ignored email's response, for your CRM or inbox to route by.

Only an email judged `not_deal_related` with at least the tenant's `skip_confidence` (0.9 by default), in a
thread that holds no deal, goes unparsed. A reply in a deal's thread is never skipped, and an unsure verdict is
parsed as usual. The classifier sees the sender and recipient domains, the subject, the start of the body and the
attachments' names and sizes, never their content. Bulk and automatic mail with no document (newsletters,
receipts, out-of-office replies) is not classified at all.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.