botserver/docs/src/chapter-05/keyword-send-mail.md

SEND MAIL

Send email messages with optional attachments and HTML formatting.

Syntax

SEND MAIL to, subject, body

Parameters

Parameter	Type	Description
to	String	Recipient email address(es), comma-separated for multiple
subject	String	Email subject line
body	String	Email body (plain text or HTML)

Description

The SEND MAIL keyword sends emails using the SMTP configuration defined in config.csv. It supports:

• Plain text and HTML emails
• Multiple recipients
• CC and BCC (via extended syntax)
• File attachments
• Email templates
• Delivery tracking

Configuration

Email settings in config.csv:

name,value
email-from,noreply@example.com
email-server,smtp.example.com
email-port,587
email-user,smtp-user@example.com
email-pass,smtp-password

Examples

Simple Text Email

SEND MAIL "user@example.com", "Welcome!", "Thank you for signing up."

Multiple Recipients

recipients = "john@example.com, jane@example.com, bob@example.com"
SEND MAIL recipients, "Team Update", "Meeting tomorrow at 3 PM"

HTML Email

body = "<h1>Welcome!</h1><p>Thank you for joining us.</p>"
body = body + "<ul><li>Step 1: Complete profile</li>"
body = body + "<li>Step 2: Verify email</li></ul>"
SEND MAIL "user@example.com", "Getting Started", body

Dynamic Content

user_name = GET "user_name"
order_id = GET "order_id"
subject = "Order #" + order_id + " Confirmation"
body = "Hello " + user_name + ", your order has been confirmed."
SEND MAIL user_email, subject, body

With Error Handling

email = HEAR "Enter your email address:"
IF VALIDATE_EMAIL(email) THEN
    SEND MAIL email, "Verification Code", "Your code is: 123456"
    TALK "Email sent successfully!"
ELSE
    TALK "Invalid email address"
END IF

Notification System

' Send notification to admin when error occurs
ON ERROR
    admin_email = GET BOT MEMORY "admin_email"
    error_details = GET_LAST_ERROR()
    subject = "Bot Error Alert"
    body = "Error occurred at " + NOW() + ": " + error_details
    SEND MAIL admin_email, subject, body
END ON

Bulk Email with Personalization

subscribers = GET "subscribers.list"
FOR EACH email IN subscribers
    name = GET "user.name"
    body = "Dear " + name + ", here's your weekly update..."
    SEND MAIL email, "Weekly Newsletter", body
    WAIT 1  ' Rate limiting
NEXT

Extended Syntax

With CC and BCC

' Using structured format
email_data = {
    "to": "primary@example.com",
    "cc": "copy@example.com",
    "bcc": "hidden@example.com",
    "subject": "Report",
    "body": "Please review attached report."
}
SEND MAIL email_data

With Attachments

' Attach file from drive
email_data = {
    "to": "user@example.com",
    "subject": "Invoice",
    "body": "Please find invoice attached.",
    "attachments": ["invoice.pdf"]
}
SEND MAIL email_data

Using Templates

' Load and fill template
template = LOAD_TEMPLATE "welcome_email"
template = REPLACE(template, "{{name}}", user_name)
template = REPLACE(template, "{{date}}", TODAY())
SEND MAIL user_email, "Welcome!", template

Email Validation

Always validate email addresses before sending:

FUNCTION IsValidEmail(email)
    IF email CONTAINS "@" AND email CONTAINS "." THEN
        parts = SPLIT(email, "@")
        IF LENGTH(parts) = 2 THEN
            domain = parts[1]
            IF domain CONTAINS "." THEN
                RETURN TRUE
            END IF
        END IF
    END IF
    RETURN FALSE
END FUNCTION

email = HEAR "Your email:"
IF IsValidEmail(email) THEN
    SEND MAIL email, "Test", "This is a test"
ELSE
    TALK "Please enter a valid email"
END IF

Delivery Status

Check email delivery status:

status = SEND MAIL "user@example.com", "Test", "Message"
IF status = "sent" THEN
    TALK "Email delivered successfully"
ELSE IF status = "queued" THEN
    TALK "Email queued for delivery"
ELSE
    TALK "Email delivery failed: " + status
END IF

Rate Limiting

Implement rate limiting to avoid spam:

last_sent = GET BOT MEMORY "last_email_time"
IF TIME_DIFF(NOW(), last_sent) < 60 THEN
    TALK "Please wait before sending another email"
ELSE
    SEND MAIL email, subject, body
    SET BOT MEMORY "last_email_time", NOW()
END IF

Error Handling

Common error scenarios:

TRY
    SEND MAIL recipient, subject, body
    TALK "Email sent successfully"
CATCH "invalid_email"
    TALK "The email address is invalid"
CATCH "smtp_error"
    TALK "Email server is unavailable"
CATCH "auth_error"
    TALK "Email authentication failed"
    LOG "Check SMTP credentials in config.csv"
END TRY

Best Practices

1. Validate Recipients: Always validate email addresses
2. Rate Limit: Implement delays for bulk emails
3. Handle Failures: Use try-catch for error handling
4. Log Attempts: Keep records of sent emails
5. Test Configuration: Verify SMTP settings before production
6. Use Templates: Maintain consistent formatting
7. Respect Privacy: Use BCC for multiple recipients
8. Include Unsubscribe: Add opt-out links for marketing emails

Security Considerations

• Never log email passwords
• Use environment variables for sensitive data
• Implement SPF, DKIM, and DMARC for deliverability
• Sanitize user input in email bodies
• Use TLS/SSL for SMTP connections

Troubleshooting

Email Not Sending

1. Check SMTP configuration in config.csv
2. Verify firewall allows port 587/465
3. Test credentials manually
4. Check email server logs

Authentication Failed

' Test SMTP connection
TEST_SMTP_CONNECTION()
IF CONNECTION_OK THEN
    TALK "SMTP connection successful"
ELSE
    TALK "Check email-user and email-pass in config.csv"
END IF

Emails Going to Spam

• Set proper FROM address
• Include text version with HTML
• Avoid spam trigger words
• Configure domain authentication (SPF/DKIM)

Related Keywords

• GET - Retrieve user data for emails
• FORMAT - Format email content
• WAIT - Rate limiting between emails
• SET SCHEDULE - Schedule email sending

Implementation

Located in src/basic/keywords/send_mail.rs

The implementation uses:

• lettre crate for SMTP
• Async email sending
• Connection pooling for performance
• Retry logic for failed attempts
• HTML sanitization for security