Email Assistant

AI-assisted workflow for drafting and sending JSON-defined emails via any SMTP-friendly mailbox (Google Workspace, Outlook, Namecheap, Proton, etc.).

Goal

Provide a minimal tool that lets me (or anyone using VS Code) draft emails as JSON, preview AI-upgraded wording directly in the terminal, and send the final version through my existing SMTP inbox without bouncing between multiple apps.

Result

Fast, consistent emails: every message is polished with OpenAI, logged, and sent in both plain text and HTML with your signature. Originally a personal tool, it's now open source for recruiters, artists, and freelancers, and will soon plug into a larger "Career Assistant" suite for research, lead discovery, email lookup, and personalized outreach.

Setup

1. Create and activate a Python 3.10+ virtual environment.
2. Install dependencies:

   pip install -r requirements.txt

3. Copy .env.example to .env and fill in:
   • OPENAI_API_KEY
   • SMTP settings for the mailbox you want to send from (host, port, username, password, sender email, SSL/TLS preference). The script only needs standard SMTP auth, so bring credentials from whichever provider you use.

Preparing an email

Place a JSON file in emails/ (or pass a custom path) with this structure:

{
  "email": "recipient@example.com",
  "subject": "Checking in",
  "text": "Original text you want the model to improve.",
  "prompt": "Structure this email"
}

Fields:

• email (required unless you pass --first/--last/--domain): recipient address.
• text (required): raw message the model should polish.
• subject (optional): defaults to "Quick update".
• prompt (optional): supply a custom instruction for the rewrite (tone, length, etc.). If omitted, the global default prompt is used.

Sending flow

python send_email.py --name sample

If --name is omitted, the script asks "Which email JSON should I send?" and looks for <name>.json in ./emails.

Workflow:

1. Loads the JSON.
2. Sends the text (plus subject/prompt when provided) to the OpenAI model for improvement.
3. Displays the upgraded body text (with your signature appended) and asks for confirmation.
4. On approval, sends a multi-part email (plain text + HTML). The HTML version includes your signature styling.
5. Logs the status to logs/email.log.

Guessing addresses (linkedin2username-style)

You can generate a cloud of likely inboxes from a first name, last name, and company domain (mirroring common linkedin2username patterns) and send the same email to each guess. Omit email from your JSON and run:

python send_email.py --name sample --first "Michael" --last "Clark" --domain example.com

The script derives addresses such as michael.clark@example.com, mclark@example.com, michaelc@example.com, clarkm@example.com, etc., shows the full list, and asks for approval before sending to each address individually.

Branding & signature

Configure .env to set:

• EMAIL_SIGNATURE: plain-text version (use \n for line breaks in the env file).
• EMAIL_SIGNATURE_HTML_FILE (recommended): path to an HTML snippet (relative paths resolve from the project root). Start from templates/signature_example.html, copy it to templates/signature.html, and adjust as needed--templates/signature.html is gitignored so your personal branding stays local.
• EMAIL_SIGNATURE_HTML (optional): direct inline HTML override if you prefer keeping the snippet inside the env file. If both are supplied, the file takes precedence.

Use the log file to audit what was sent (success/failure + source JSON).

Note: Every email body is rewritten by the OpenAI model before sending. Review the AI-modified text carefully at the confirmation step to ensure it reflects exactly what you intend to say.