# Messages to investors

Ray sends nothing and writes no message. You write the draft and the user sends it. Ray says who to write to, what stands in the way, how old its own knowledge is, and what may be said about the raise. This guide covers an email, a note on another channel, and one message that goes to many investors.

## The order of work

1. Call `get_email_context` with the refcode of the deal, the person or the firm. For a message to many investors, call it with the round. Read its `company_playbook`: how the company writes to investors, and the group each recipient is in.
2. Put every item in `stops` to the user before you draft.
3. Catch up from the user's mail and calendar, as `catch_up` describes.
4. Draft from the result together with what you found.
5. Leave the draft for the user. Do not send it unless the user asks you to and your client has a tool that can.
6. After the user sends it, record that it went out.

Do the first three steps every time, including when the user says "just a quick follow-up". A message that ignores a pass, a teammate's message from yesterday or the investor's own latest reply is the failure this order exists to prevent.

## Stops

Each stop has an `action`. `do_not_send` means write nothing to that person unless the user decides otherwise knowing the reason: a do-not-contact mark on the person or their firm. `ask_first` means give the user the reason and let them decide: they or their firm are on a list the company's playbook holds back (`held_back`), the investor passed or was set aside (for a message to a round, one stop for each such investor), the round is not running, a teammate owns the deal, a teammate was in touch in the last few days, or one person is on two live deals in the same round.

Give the user the stop's `detail` in your own words and wait for their answer. Do not draft around a stop, soften it, pick the option you think they would choose, or save a draft first and ask afterwards. The one answer you may take without asking is the company's own, written in its playbook for that kind of stop ("people who passed still get the community update, with no ask"); follow it and tell the user, with the draft, which stops it answered. Nothing answers a `do_not_send` or `held_back` stop but the user, knowing the reason. An empty `stops` list means Ray knows of nothing in the way. It does not mean nothing is.

## Catch up before drafting

Ray knows only what it was told. `catch_up.investors` gives, for each investor, the time of the last exchange Ray holds (`known_through`) and the names, addresses and firm domain to look for. Search the user's mail and calendar from that time on. When `known_through` is empty, Ray holds nothing, so search without a start date.

Record an exchange when it changed where the deal stands or what someone owes: a reply with an answer, a meeting that was held or booked, a document they asked for, a decision. Skip scheduling back-and-forth, automatic replies, newsletters and anything the capture rules already rule out. One real event is one record, however many messages carried it.

Record each one with `record_event` and `found_in`: the provider's id for the message or event, the thread id, the subject, and every address on it except the user's own. Set `event.occurred_at` to when the message was sent or the event was held. Summarize what happened in a sentence or two. Do not paste the message body.

`found_in` is for anything the user did not state to you, including when the user asked you to go through their inbox. Asking for the search is not stating what it found. Leave `found_in` out only for what the user told you themselves, even when a message also shows it. Never drop it to get a write through.

Read the status of each result:

- `proposed`: it is waiting in Captures to Review, private to the user. Keep the proposal's refcode (`proposal` in the result). Do not submit it again in other words.
- `excluded`: a capture exclusion covers it and nothing was stored. Do not record it another way, as a note, a task, or the same call without `found_in`. It is still the user's own mail and may inform the draft.
- `already_recorded`: Ray has it. Nothing to do.
- `no_write`: the user's rule for their calendar and inbox is Observe. Stop submitting what you find.
- `needs_resolution`: ask the question it returns, as for any event.

Then draft from the result and what you found, without waiting for the user to approve the proposals. Tell the user, with the draft, what you found and how many proposals are waiting. `catch_up.waiting_for_approval` counts proposals from earlier sessions that Ray also lacks; read them in `get_fundraising_context` when the count is not zero.

If you cannot read the user's mail or calendar, say so and ask whether anything has happened since `known_through`. Do not present the draft as up to date.

## What to write from

- `recipients`: who to write to. The first address is the one they prefer. When `preferred_channel` is set, they asked to be reached another way; say so before drafting an email. A recipient of kind `firm` is the firm's own address, offered because nobody at the firm is on record: write so the message can be passed to the right partner, say what the company is and what it asks for in the first lines, and when someone replies, record whom they name with `save_contact`. A `submission_form` is for the user to fill in; mention it and do not treat it as a sent message.
- `deals`: where each deal stands and who owes the next move. A message normally comes from the deal's owner.
- `open_tasks`: what is owed. This is usually the reason for the message.
- `recent_events`: the last real exchange. Pick up from it and do not repeat what was already said.
- `already_sent`: which version of each document they have. Do not present a version they already have as new. When `newer_version` is true, a later one exists that they have not been sent.
- `introductions`: who introduced them or was asked to. One with `asked_of_them` is something this person was asked to do, such as a connector asked for introductions, with `target` empty until they named someone: pick up from that ask rather than asking again.
- `rounds`: what may be said about the raise. Take the amount, the use of the money, dates and milestones from the plan's narrative. Add no figure it does not contain: not a valuation, a traction number or a date.
- `missing`: what the message would need that Ray does not hold. Ask the user for it. Do not invent it and do not write around it silently.
- `company_playbook`: the company's own way of writing to investors. Its `messages` section applies to every message, and for a message written to one person, the first of their groups that gets an ask says what they get: the purpose, the ask, the angle, who sends it. An announcement group is a message of its own to its whole list, and a held-back group is a `held_back` stop. Follow it unless the user tells you otherwise for this message. It is internal: do not quote it to the investor. When it gives the company's answer to an `ask_first` stop, you may follow that answer, and you say so to the user with the draft. It never answers a `do_not_send` stop.

What Ray holds about an investor is the company's private record. Use it to decide what to say and do not repeat it to them: not the stage, the priority, an expected amount, a secondhand report or a note. Say nothing about other investors, named or not, unless the user tells you to; "one investor is at the commitment stage" is their private state too.

Write in the user's voice. When you can read their sent mail, match how they write to this person. Otherwise keep it short and plain. `get_meeting_brief` has background on the people when the message needs it.

## Messages to a group

A group is a contact list the company's playbook describes ("do the community update", "the angels outreach"). Call `get_email_context` with the list's refcode or exact name; `list_records` with kind `contact_list` finds it. It returns one page of `members`; continue with `next_offset` until it is empty, and tell the user how many there are. Each member carries `emails` and, when Ray has one, `linkedin`, for a message sent through LinkedIn instead; record such a message as type `message`. For one text to everyone, the list's page on the site offers the same addresses as one block to paste into a BCC field.

- Leave off every member with `leave_off`, and tell the user who and why, in one line for each reason: a do-not-contact mark, a list the playbook holds back (or a firm on one that they work at), an earlier group that gets an ask and covers them (they get that group's message), or the playbook's own answer. A firm's `held_back_people` are already left out of its recipients; name them too. An announcement covers nobody: its members get it whatever other groups they are in. A held-back list gets no message to a group, and Ray refuses one.
- Put the remaining `stops` to the user before drafting, as for one investor. The stops in `answered` are settled by the playbook: apply them, and say in the same reply which ones and what the playbook says. Do not ask about them again.
- The group's entry in `company_playbook` says what the group gets. When it is one text for everyone (an announcement), write one text from the round's plan and the company's story, and send nothing yourself. Put no member's address where the others can see it unless the user asks. When each person gets a message of their own, write one per member, calling `get_email_context` for a member when you need their history.
- A person recorded twice can get the message twice, or get it from the record without their do-not-contact mark. Before a first send to a group, check its members for duplicates as [Duplicates](duplicates.md) describes.
- Catch up from the user's mail with the catch-up list as for one investor. With many members, catch up on those with a live deal first and say how far you got.

For a round, `get_email_context` with the round's refcode returns its plan and the catch-up list for every deal; leave out everyone marked `do_not_contact` and everyone its `held_back` stop names unless the user says otherwise, and ask the user which of the others to include, since investors who passed are not included by default.

## After it is sent

A draft is not a sent message. Record nothing as sent until the user says it went out. When they say it did, record it then, on their word, under the rule for what they tell you: do not ask them to confirm it, and do not wait until you can find it in their mail. You may look in their sent mail for when it went and what it said; if it is not there (sent from a phone or another account, or not synced yet), record it anyway and say you could not see it. Even when you find it there, it is still their statement: record it without `found_in`, which would turn it into a proposal under the rule for their calendar and inbox. If you see the sent message in their mail and the user has not told you, record it with `found_in` like anything else you found.

Use `record_event` with type `email`, or `record_document_share` when a document went with it, naming the exact version. A message with one text sent to a group is recorded once with `record_group_message`: the list, the subject, the members it went to (`sent_to`, by refcode) and the document version if one went with it. It is one record on no deal, so do not also record it on each deal. Messages written for each person are recorded with `record_event`, one per person. If the message completes a task, complete it with `save_task`. Who owes the next move changes only when the user says so; suggest it if it looks right.