send-email-programmatically

What this skill does

# Send Email Programmatically

Send emails via SMTP, free APIs (Mailgun, SendGrid free tier), or privacy-focused services. Essential for notifications, alerts, automated reports, and user communication.

## When to use

- Use case 1: When the user asks to send email notifications or alerts
- Use case 2: When you need to deliver automated reports or summaries
- Use case 3: For error logging and monitoring alerts
- Use case 4: When building user communication workflows (confirmations, updates)

## Required tools / APIs

- **curl** — For API-based email sending (pre-installed on most systems)
- **sendmail** / **msmtp** — For SMTP email sending
- **Mailgun API** — Free tier: 5,000 emails/month (requires API key)
- **SendGrid API** — Free tier: 100 emails/day (requires API key)
- **mail.tm** — Temporary email API (no API key required)

Install options:

```bash
# Ubuntu/Debian
sudo apt-get install -y curl msmtp msmtp-mta

# macOS (postfix is pre-installed, or use msmtp)
brew install msmtp

# Node.js
npm install nodemailer
```

## Skills

### send_email_via_smtp_curl

Send email using SMTP via curl (works with Gmail, Outlook, custom SMTP servers).

```bash
# Gmail SMTP example (requires app password)
SMTP_SERVER="smtp.gmail.com:587"
FROM_EMAIL="[email protected]"
TO_EMAIL="[email protected]"
SUBJECT="Test Email"
BODY="This is a test email sent via SMTP."
APP_PASSWORD="your-app-password"

# Send email
curl -v --url "smtp://${SMTP_SERVER}" \
  --mail-from "${FROM_EMAIL}" \
  --mail-rcpt "${TO_EMAIL}" \
  --user "${FROM_EMAIL}:${APP_PASSWORD}" \
  --upload-file - <<EOF
From: ${FROM_EMAIL}
To: ${TO_EMAIL}
Subject: ${SUBJECT}

${BODY}
EOF

# Outlook/Office365 SMTP
curl --url "smtp://smtp.office365.com:587" \
  --mail-from "[email protected]" \
  --mail-rcpt "[email protected]" \
  --user "[email protected]:your-password" \
  --ssl-reqd \
  --upload-file - <<EOF
From: [email protected]
To: [email protected]
Subject: Hello from Outlook

This is an automated email.
EOF
```

### send_email_via_mailgun_api

Send email using Mailgun free tier (5,000 emails/month, no credit card required for sandbox).

```bash
# Set your Mailgun credentials
MAILGUN_API_KEY="your-mailgun-api-key"
MAILGUN_DOMAIN="sandbox123.mailgun.org"  # or your verified domain

# Send email
curl -s --user "api:${MAILGUN_API_KEY}" \
  "https://api.mailgun.net/v3/${MAILGUN_DOMAIN}/messages" \
  -F from="Sender Name <mailgun@${MAILGUN_DOMAIN}>" \
  -F to="[email protected]" \
  -F subject="Hello from Mailgun" \
  -F text="This is the plain text body" \
  -F html="<h1>HTML Email</h1><p>This is the HTML body</p>"

# Send with attachment
curl -s --user "api:${MAILGUN_API_KEY}" \
  "https://api.mailgun.net/v3/${MAILGUN_DOMAIN}/messages" \
  -F from="notifications@${MAILGUN_DOMAIN}" \
  -F to="[email protected]" \
  -F subject="Report Attached" \
  -F text="Please find the report attached." \
  -F attachment=@./report.pdf
```

**Node.js:**

```javascript
async function sendEmailMailgun(options) {
  const { apiKey, domain, from, to, subject, text, html } = options;
  
  const formData = new URLSearchParams({
    from,
    to,
    subject,
    text: text || '',
    html: html || ''
  });
  
  const auth = 'Basic ' + Buffer.from(`api:${apiKey}`).toString('base64');
  
  const res = await fetch(`https://api.mailgun.net/v3/${domain}/messages`, {
    method: 'POST',
    headers: {
      'Authorization': auth,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });
  
  if (!res.ok) {
    const error = await res.text();
    throw new Error(`Mailgun API error: ${error}`);
  }
  
  return await res.json();
}

// Usage
// sendEmailMailgun({
//   apiKey: 'your-mailgun-api-key',
//   domain: 'sandbox123.mailgun.org',
//   from: 'Sender <[email protected]>',
//   to: '[email protected]',
//   subject: 'Test Email',
//   text: 'Plain text body',
//   html: '<h1>HTML body</h1>'
// }).then(result => console.log('Email sent:', result));
```

### send_email_via_sendgrid_api

Send email using SendGrid free tier (100 emails/day).

```bash
# Set your SendGrid API key
SENDGRID_API_KEY="your-sendgrid-api-key"

# Send email
curl -s --request POST \
  --url "https://api.sendgrid.com/v3/mail/send" \
  --header "Authorization: Bearer ${SENDGRID_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "personalizations": [{
      "to": [{"email": "[email protected]"}],
      "subject": "Hello from SendGrid"
    }],
    "from": {"email": "[email protected]", "name": "Sender Name"},
    "content": [{
      "type": "text/plain",
      "value": "This is the email body."
    }]
  }'

# Send HTML email with attachment
curl -s --request POST \
  --url "https://api.sendgrid.com/v3/mail/send" \
  --header "Authorization: Bearer ${SENDGRID_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "personalizations": [{
      "to": [{"email": "[email protected]"}]
    }],
    "from": {"email": "[email protected]"},
    "subject": "Weekly Report",
    "content": [{
      "type": "text/html",
      "value": "<h1>Weekly Report</h1><p>Attached is your report.</p>"
    }],
    "attachments": [{
      "content": "'"$(base64 -w 0 report.pdf)"'",
      "filename": "report.pdf",
      "type": "application/pdf"
    }]
  }'
```

**Node.js:**

```javascript
async function sendEmailSendGrid(options) {
  const { apiKey, from, to, subject, text, html, attachments = [] } = options;
  
  const payload = {
    personalizations: [{
      to: [{ email: to }],
      subject
    }],
    from: { email: from },
    content: [{
      type: html ? 'text/html' : 'text/plain',
      value: html || text
    }]
  };
  
  if (attachments.length > 0) {
    payload.attachments = attachments.map(att => ({
      content: att.content,  // base64 string
      filename: att.filename,
      type: att.type || 'application/octet-stream'
    }));
  }
  
  const res = await fetch('https://api.sendgrid.com/v3/mail/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
  
  if (!res.ok) {
    const error = await res.text();
    throw new Error(`SendGrid API error: ${error}`);
  }
  
  return { success: true, status: res.status };
}

// Usage
// sendEmailSendGrid({
//   apiKey: 'your-sendgrid-api-key',
//   from: '[email protected]',
//   to: '[email protected]',
//   subject: 'Test Email',
//   html: '<h1>Hello</h1><p>This is a test.</p>'
// }).then(result => console.log('Email sent:', result));
```

### send_email_via_msmtp

Send email using msmtp (lightweight SMTP client, good for automation).

```bash
# Configure msmtp (one-time setup)
cat > ~/.msmtprc <<EOF
defaults
auth           on
tls            on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile        ~/.msmtp.log

# Gmail account
account        gmail
host           smtp.gmail.com
port           587
from           [email protected]
user           [email protected]
password       your-app-password

# Set default account
account default : gmail
EOF

chmod 600 ~/.msmtprc

# Send email
echo -e "Subject: Test Email\nFrom: [email protected]\nTo: [email protected]\n\nThis is the email body." | msmtp [email protected]

# Send email with file content
cat report.txt | msmtp -t <<EOF
To: [email protected]
From: [email protected]
Subject: Daily Report

$(cat report.txt)
EOF

# Send HTML email
msmtp [email protected] <<EOF
To: [email protected]
From: [email protected]
Subject: HTML Email
Content-Type: text/html

<html>
<body>
  <h1>Hello</h1>
  <p>This is an HTML email.</p>
</body>
</html>
EOF
```

### send_email_nodejs_nodemailer

Send email using Node.js nodemailer library (supports all SMTP servers).

**Node.js:**

```javascript
const nodemailer = require('nodemailer');

async function sendEmail(config) {
  const {
    smtpHost,
    smtpPort,
    smtpUse