Vendor Email Writing Guide

This guide summarizes patterns and best practices for writing emails to external vendors, derived from analysis of the Integration team’s Draft Emails database.

Email Structure

Standard Format

To:
    [Primary recipient name and email]
CC:
    [Additional recipients]
    integration-support@rightcapital.com

[Greeting]

[Body content]

[Closing]
[Signature]

Subject Line Conventions

Prefix	Usage	Example
Urgent:	Critical production issues requiring immediate attention	Urgent: SSL certificate expired on https://api.vendor.com
Re:	Follow-up replies	Re: Advyzon API rate limit errors since Jan 20, 2026
(none)	Standard requests, proposals, clarifications	Request Clarification on an Addepar API Error

Best Practices:

• Keep subject lines concise but descriptive
• Include specific identifiers (API names, error codes) when relevant
• Avoid vague subjects like “Question” or “Issue”

Greeting Patterns

Greeting	When to Use
Hi [Name],	Default - when you know the recipient
Hi Team,	When emailing a group or support team
Hi [Name] and [Team] Team,	When addressing both individual and team

Optional pleasantry (use sparingly):

• “Hope you’re doing well.”
• “Hope you are doing well.”

Closing Patterns

Closing	Formality
Thanks,	Standard, most common
Thank you,	Slightly more formal
Best regards,	Formal, for proposals
Best,	Brief, for ongoing threads
Looking forward to your thoughts!	When requesting feedback

Email Categories & Templates

1. Urgent Issue Report

Use when: Production systems are failing, immediate vendor action required.

Key Elements:

• Urgent: prefix in subject
• State the issue immediately
• Provide exact timestamp (with timezone, typically ET)
• Include technical details (endpoint, error message)
• Clearly state the impact on mutual advisors
• Request confirmation and expected resolution timeline

Example Structure:

Hi [Name],

I am [Your Name] from the RightCapital Integration Team. I'm reaching out because
[brief description of the issue].

Since around **[Date Time] ET**, our requests to `[endpoint]` have been failing
with the following error:
`[Error message]`

Example endpoint:
`[Full URL example]`

This issue is impacting our mutual advisors and is preventing us from [impact].
Could you please confirm [what you need] and let us know when you expect it
to be resolved?

2. Technical Investigation / Bug Report

Use when: Reporting API errors, unexpected behavior, or data inconsistencies.

Key Elements:

• Clear problem statement
• Detailed timeline with specific timestamps
• Complete request/response logs in code blocks
• Your analysis of potential causes
• Constructive suggestions for improvement

Example Structure:

Hi Team,

We have received a report from a mutual advisor (User ID: [ID]) indicating
that [description of the issue].

After investigation, we found that [technical findings].

Below are examples from our recent logs (all times are in Eastern Time):

**Example 1:**
- **[Timestamp]**: [Action taken]
- **[Timestamp]**: [Result observed]

[Include request/response in code blocks]

Could you please investigate [specific question]?

3. Clarification Request

Use when: You need the vendor to confirm or explain API behavior.

Key Elements:

• Explain the context/background
• State what you observed
• Ask a specific, answerable question
• Explain why the answer matters

Example Structure:

Hi [Name/Team],

Hope you're doing well.

We've received reports from our mutual advisors that [situation].

Upon investigation, we found that the API `[endpoint]` returns [behavior]
with the following message: `[message]`

Could you please confirm if [specific question]? Understanding this clearly
will help us [why it matters].

FYI, below are the API response details:
[code block with details]

4. Follow-up / Reply Email

Use when: Responding to vendor’s reply, providing additional context.

Key Elements:

• Reference previous discussion briefly
• Address their points directly
• Provide new information or counter-arguments
• Propose constructive alternatives
• Keep a collaborative tone

Example Structure:

Hi [Name],

Regarding [their point]: [your response with reasoning].

[Additional context or data to support your position]

To [address the issue/improve the situation], one improvement we can think of
is [suggestion]. [Explain the benefit].

Also, as a suggestion: [additional recommendation if applicable].

Thanks,

5. Proposal / Status Update

Use when: Sharing project plans, requesting alignment on frameworks.

Key Elements:

• Clear sections with headers
• Background context
• Structured proposal with specifics
• Benefits clearly articulated
• Next steps with actionable items
• Invitation for feedback

Example Structure:

Hi [Name],

Following up on our discussion from [when], I wanted to provide [what].

## Background
[Context and problem statement]

## Proposal / Project Details
### 1. [First item]
**Scope**: [Description]
**Key Benefits:**
- [Benefit 1]
- [Benefit 2]

### 2. [Second item]
[...]

## Next Steps
We'd love to get your input on:
1. [Question 1]
2. [Question 2]

Looking forward to your thoughts!

Technical Content Best Practices

Including API Details

Always use code blocks for technical content:

**Request**
```json
curl -X POST 'https://api.vendor.com/endpoint' \
  --header 'Authorization: ******' \
  --header 'Content-Type: application/json' \
  --data '{
  "parameter": "value"
}'
```

**Response**
```json
{
  "status_code": 400,
  "body": {
    "error": "error_message"
  }
}
```

Highlighting Key Information

• Use bold for important values: dates, endpoints, error codes
• Use backticks for technical terms: API names, URLs, field names
• Use bullet points for multiple items or questions

Timestamp Format

Always include timezone and be specific:

• Preferred: “Jan 26, 2026 7:59 PM EST”
• Alternative: “2025-11-06 21:37:07 (Eastern Time)“

Language & Tone Guidelines

Do’s

Practice	Example
Use “mutual advisors” to emphasize shared interest	”This is impacting our mutual advisors”
Be direct but polite	”Could you please investigate…”
Provide context for your requests	”Understanding this will help us…”
Offer constructive suggestions	”We suggest that the API should return…”
Acknowledge their perspective	”We understand that… However…”

Don’ts

Avoid	Instead
Accusatory language	Focus on the problem, not blame
Vague requests	Be specific about what you need
Over-apologizing	State facts professionally
Excessive formality	Keep it professional but approachable
Burying the main point	Lead with the key issue

Framing Requests

Offering options (when appropriate):

We would really appreciate your help with one of the following:
- **Restore** the previous behavior for our integration
- If reverting is not possible, please [alternative option]

Asking for confirmation:

Could you please confirm whether `[value]` is exactly [what you think]?
We're asking because [reasoning], and we want to make sure [outcome].

Requesting additional context:

If [condition], it would be very helpful if you could share:
- **Background:** [Question about why]
- **Scope:** [Question about extent]
- **Timing:** [Question about timeline]

American Business Email Culture

When communicating with US-based vendors, understanding American business email conventions helps ensure effective communication.

Core Principles

1. Direct Communication

Americans value directness and clarity. Get to the point quickly.

Pattern	Example
Lead with the ask	”I’m writing to request…” not “I hope this email finds you well. I wanted to reach out regarding…”
State problems clearly	”The API is returning 500 errors” not “We’ve noticed some slight irregularities”
Be explicit about needs	”We need this resolved by Friday” not “It would be nice if this could be addressed soon”

Key insight: What might feel “too direct” in other cultures is often perceived as professional and respectful of the recipient’s time in American business.

2. Action-Oriented Writing

Every email should have a clear purpose and desired outcome.

❌ "I wanted to touch base about the API issues we discussed."

✅ "Following up on our API discussion - could you confirm whether
   the fix has been deployed to production?"

3. Positive Framing

Frame issues constructively, focusing on solutions rather than problems.

Instead of	Write
”Your API is broken"	"We’re encountering an issue with the API"
"This is unacceptable"	"This is significantly impacting our users"
"You never responded"	"I wanted to follow up on my previous email"
"This is wrong"	"We noticed a discrepancy that we’d like to clarify”

Common American Email Phrases

Opening Phrases

Phrase	Usage
”I’m reaching out because…”	Standard opener, gets to the point
”Following up on…”	For follow-up emails
”I wanted to loop you in on…”	When adding someone to a thread
”Quick question:“	For simple requests
”Heads up:“	Informal alert about something

Transitional Phrases

Phrase	Usage
”That said,…”	Introducing a counterpoint
”On a related note,…”	Shifting topics
”To clarify,…”	Providing more detail
”Just to confirm,…”	Verifying understanding
”For context,…”	Adding background information

Closing Phrases

Phrase	Usage
”Let me know if you have any questions”	Standard, invites dialogue
”Happy to discuss further”	Offering more conversation
”Please advise”	Requesting guidance/decision
”Looking forward to hearing from you”	Expecting a response
”Thanks in advance”	When requesting something

Softening Phrases (Use Sparingly)

Phrase	Effect
”I was wondering if…”	Polite request
”Would it be possible to…”	Asking for something non-routine
”If it’s not too much trouble…”	Extra polite, use rarely
”When you get a chance…”	Low-priority request

Technical Email Specifics

Vocabulary Preferences

Use simple, common words over complex alternatives:

Prefer	Over
”use"	"utilize"
"help"	"assist” / “facilitate"
"need"	"require"
"start"	"commence” / “initiate"
"end"	"terminate” / “conclude"
"find out"	"ascertain"
"check"	"verify” / “validate"
"fix"	"remediate"
"show"	"demonstrate"
"about"	"regarding” / “concerning”

Technical Clarity

When describing technical issues:

❌ "The aforementioned endpoint is experiencing intermittent failures
   resulting in suboptimal user experiences."

✅ "The /api/accounts endpoint is returning 500 errors about 20% of
   the time, causing sync failures for affected users."

Best practices:

• Use specific numbers instead of vague qualifiers (“20% of requests fail” vs “some requests fail”)
• Include concrete examples (actual error messages, request IDs)
• Avoid jargon the recipient might not know
• Define acronyms on first use if not universally known

Asking Technical Questions

Structure technical questions for easy answering:

❌ "Can you tell us about how the rate limiting works and what we
   should do about it?"

✅ "We have a few questions about your rate limiting:
   1. What is the current limit? (requests per minute/second?)
   2. Does it apply per-API-key or per-endpoint?
   3. Is there a way to request a higher limit for our integration?"

Email Length & Formatting

The “Skimmable” Principle

Busy engineers often skim emails. Make your emails easy to scan:

• Short paragraphs: 2-3 sentences max
• Bullet points: For lists of items
• Bold key terms: Draw attention to important info
• Clear sections: Use headers for longer emails
• TL;DR: For long emails, consider a summary at the top

Ideal Structure for Technical Emails

[One-line summary of the issue/request]

[2-3 sentences of context]

[Technical details in bullet points or code blocks]

[Clear ask: what do you need from them?]

[Closing]

Timing & Response Expectations

Business Hours

• US business hours: 9 AM - 5 PM in recipient’s timezone
• Be aware of US timezone differences (ET, CT, MT, PT)
• Avoid sending urgent requests late Friday (won’t be seen until Monday)

Response Time Norms

Urgency	Typical Response Time	How to Signal
Critical	Same day	”Urgent:” in subject, call if needed
High	1-2 business days	Clear deadline in email
Normal	2-5 business days	Standard email
Low	1 week+	“When you get a chance…”

Following Up

• Wait at least 2-3 business days before following up on non-urgent items
• Keep follow-ups brief and friendly
• Reference your previous email with date

Hi [Name],

I wanted to follow up on my email from Tuesday about the API errors.
Have you had a chance to look into this?

Thanks,

Common Mistakes to Avoid

1. Over-Formality

❌ "Dear Sir/Madam, I hope this correspondence finds you in good health.
   I am writing to humbly request your esteemed assistance..."

✅ "Hi Team, I'm reaching out about an API issue we're seeing..."

2. Excessive Hedging

❌ "I was just kind of wondering if maybe it might possibly be okay
   if we could perhaps look into..."

✅ "Could you look into this issue?"

3. Wall of Text

Break up long paragraphs. Use formatting. Make it scannable.

4. Unclear Action Items

❌ "It would be great if someone could take a look at this when
   there's time and let us know what you think."

✅ "Could you investigate this and let us know by Friday what's
   causing the 500 errors?"

5. Missing Context

Don’t assume the recipient remembers previous conversations. Provide enough context.

6. Passive Voice Overuse

❌ "It has been observed that errors are being returned by the API."

✅ "We're seeing the API return 500 errors."

Cultural Notes

Informality is Professional

In American tech culture, casual ≠ unprofessional:

• First names are standard (not Mr./Ms.)
• “Hi” is preferred over “Dear”
• Contractions are fine (don’t, won’t, can’t)
• Brief emails are respectful of time

Gratitude is Expected

Always thank people for their help, even in advance:

• “Thanks for looking into this”
• “I appreciate your help with this”
• “Thanks in advance for your assistance”

Optimism Bias

American business communication tends toward optimism:

• Focus on solutions, not just problems
• Express confidence in resolution
• Avoid overly negative framing

CC and Recipient Guidelines

When to CC integration-support@rightcapital.com

Always CC integration-support@rightcapital.com on:

• Issue reports and bug reports
• Ongoing technical discussions
• Any communication that may need follow-up

Choosing Recipients

• Primary contact known: Address them directly
• Support team: Use their support email address
• Multiple stakeholders: Address primary contact, CC others

Review Checklist

Before sending, verify:

• Subject line clearly describes the purpose
• Recipient and CC list are correct
• Problem/request is stated early in the email
• Technical details are in properly formatted code blocks
• Timestamps include timezone (typically ET)
• Impact on mutual advisors is mentioned (if applicable)
• Specific questions or action items are clear
• Tone is professional and collaborative
• Email is reviewed by a team member (for important communications)

Related Resources

• Notion Draft Emails Database - Review past emails for reference
• The database workflow: Draft → Reviewing → Sent Out