Notifications

sendAgentEmail()

Sends an email via the PhoneClaw agent email service. Useful for notifications, alerts, and automation reports.

string

required

Recipient email address.

string

required

Email subject line.

string

required

Email body content. Supports plain text only.

void

Sends email asynchronously. Success/failure is spoken via TTS.

Basic Usage

// Simple notification
Android.sendAgentEmail(
  "user@example.com",
  "Automation Complete",
  "Your scheduled task has finished successfully."
);

// Alert email
Android.sendAgentEmail(
  "admin@example.com",
  "Error Alert",
  "An error occurred during automation execution."
);

Practical Examples

// Send daily automation summary
function sendDailyReport() {
  const stats = {
    tasksCompleted: 15,
    errors: 2,
    postsCreated: 5,
    messagesChecked: 23
  };
  
  const report = `Daily Automation Report
  
Tasks Completed: ${stats.tasksCompleted}
Errors Encountered: ${stats.errors}
Posts Created: ${stats.postsCreated}
Messages Checked: ${stats.messagesChecked}

Report generated at: ${new Date().toLocaleString()}`;
  
  Android.sendAgentEmail(
    "admin@example.com",
    "PhoneClaw Daily Report - " + new Date().toLocaleDateString(),
    report
  );
  
  Android.speakText("Daily report sent");
}

// Schedule daily at 6 PM
Android.schedule("sendDailyReport()", "0 0 18 * * *");

// Send immediate error alerts
function handleError(errorType, errorMessage) {
  const email = `Error Alert
  
Type: ${errorType}
Message: ${errorMessage}
Timestamp: ${new Date().toISOString()}
Device: Android Phone

Please investigate this issue.`;
  
  Android.sendAgentEmail(
    "alerts@example.com",
    "🚨 PhoneClaw Error: " + errorType,
    email
  );
  
  Android.speakText("Error notification sent");
}

try {
  // Automation code
  performTask();
} catch (e) {
  handleError("Task Failure", e.message);
}

// Notify on successful completion
function notifySuccess(taskName, details) {
  const message = `Task Completed Successfully
  
Task: ${taskName}
Details: ${details}
Completed At: ${new Date().toLocaleString()}

Your automation workflow has finished.`;
  
  Android.sendAgentEmail(
    "user@example.com",
    "✓ Task Complete: " + taskName,
    message
  );
}

function postToInstagram() {
  // ... posting logic ...
  notifySuccess("Instagram Post", "Posted photo with caption");
}

// Send periodic status updates
function sendStatusUpdate() {
  const uptime = Math.floor(Math.random() * 100); // Example
  const status = uptime > 95 ? "Excellent" : "Good";
  
  const update = `PhoneClaw Status Update
  
Status: ${status}
Uptime: ${uptime}%
Last Check: ${new Date().toLocaleString()}

All systems operational.`;
  
  Android.sendAgentEmail(
    "monitoring@example.com",
    "PhoneClaw Status - " + status,
    update
  );
}

// Send status every 6 hours
Android.schedule("sendStatusUpdate()", "0 0 */6 * * *");

Implementation Details

Source Location

MainActivity.kt:738

@JavascriptInterface
fun sendAgentEmail(to: String, subject: String, message: String) {
    CoroutineScope(Dispatchers.IO).launch {
        try {
            val securityKey = "af3j2kdw234" // same as your Node.js endpoint
            val apiUrl = "https://yourserver.com/sendAgentEmail" // update to your real server
            
            val json = JSONObject().apply {
                put("security", securityKey)
                put("to", to)
                put("subject", subject)
                put("message", message)
            }
            
            val client = OkHttpClient.Builder()
                .connectTimeout(30, TimeUnit.SECONDS)
                .readTimeout(30, TimeUnit.SECONDS)
                .build()
            
            val body = json.toString()
                .toRequestBody("application/json".toMediaTypeOrNull())
            
            val request = Request.Builder()
                .url(apiUrl)
                .post(body)
                .addHeader("Content-Type", "application/json")
                .build()
            
            val response = client.newCall(request).execute()
            val responseBody = response.body?.string() ?: ""
            
            if (response.isSuccessful) {
                Log.i("AndroidJSInterface", "Email sent successfully: $responseBody")
                speakText("Email sent to $to")
            } else {
                Log.e("AndroidJSInterface", "Email send failed: ${response.code} ${responseBody}")
                speakText("Failed to send email to $to")
            }
        } catch (e: Exception) {
            Log.e("AndroidJSInterface", "Error sending email: ${e.message}")
            speakText("Error sending email")
        }
    }
}

Email Service

The function sends emails through a backend API:

HTTP POST to configured server endpoint
Requires security key authentication
30-second timeout for requests
Asynchronous execution (non-blocking)

Email delivery is asynchronous. The function returns immediately while the email is sent in the background.

Configuration

The email server endpoint URL and security key are configured in the MainActivity source code. You must update these values to use your own email service.

To configure the email service:

Set up a backend email API endpoint
Update apiUrl in MainActivity.kt:742
Update securityKey in MainActivity.kt:741
Rebuild the app

Backend API Format

Your email endpoint should accept:

{
  "security": "your-security-key",
  "to": "recipient@example.com",
  "subject": "Email subject",
  "message": "Email body"
}

And return:

{
  "success": true,
  "messageId": "abc123"
}

Complete Examples

Automation Report System

const ADMIN_EMAIL = "admin@example.com";

function sendAutomationReport(taskName, status, details) {
  const timestamp = new Date().toLocaleString();
  const statusEmoji = status === "success" ? "✓" : "✗";
  
  const report = `
Automation Report
${'='.repeat(50)}

Task: ${taskName}
Status: ${statusEmoji} ${status.toUpperCase()}
Timestamp: ${timestamp}

Details:
${details}

${'='.repeat(50)}
Generated by PhoneClaw
  `;
  
  Android.sendAgentEmail(
    ADMIN_EMAIL,
    `${statusEmoji} ${taskName} - ${status}`,
    report
  );
}

// Usage
function postToSocialMedia() {
  try {
    // ... posting logic ...
    sendAutomationReport(
      "Social Media Post",
      "success",
      "Posted to Instagram with caption"
    );
  } catch (e) {
    sendAutomationReport(
      "Social Media Post",
      "failed",
      "Error: " + e.message
    );
  }
}

Multi-Recipient Notifications

function notifyTeam(subject, message) {
  const recipients = [
    "admin@example.com",
    "dev@example.com",
    "ops@example.com"
  ];
  
  recipients.forEach(email => {
    Android.sendAgentEmail(email, subject, message);
    Android.delay(1000); // Avoid rate limiting
  });
  
  Android.speakText("Team notified");
}

// Usage
notifyTeam(
  "System Alert",
  "Critical automation failure detected"
);

Scheduled Reports

// Weekly summary every Monday at 9 AM
Android.schedule("sendWeeklyReport()", "0 0 9 * * 1");

function sendWeeklyReport() {
  const report = generateWeeklyStats();
  
  Android.sendAgentEmail(
    "reports@example.com",
    "Weekly Automation Report - Week " + getWeekNumber(),
    report
  );
  
  Android.speakText("Weekly report sent");
}

function generateWeeklyStats() {
  return `Weekly Summary
  
Tasks Run: 150
Success Rate: 95%
Errors: 7
Uptime: 99.2%

Top Tasks:
1. Instagram posts: 35
2. Message checks: 84
3. Data collection: 31`;
}

function getWeekNumber() {
  const now = new Date();
  const start = new Date(now.getFullYear(), 0, 1);
  const diff = now - start;
  const oneWeek = 1000 * 60 * 60 * 24 * 7;
  return Math.ceil(diff / oneWeek);
}

Best Practices

Use descriptive subject lines

Include context in subjects for easy filtering and prioritization.

// Good
Android.sendAgentEmail(
  "user@example.com",
  "[PhoneClaw] Instagram Post Failed - 2024-03-15",
  "Details..."
);

// Avoid
Android.sendAgentEmail(
  "user@example.com",
  "Error",
  "Something went wrong"
);

Include timestamps and context

Always include when and where events occurred.

const context = `
Timestamp: ${new Date().toISOString()}
Device: ${getDeviceId()}
Task: ${taskName}
Details: ${details}`;

Android.sendAgentEmail("user@example.com", subject, context);

Avoid email spam

Rate-limit notifications to prevent flooding inboxes.

let lastEmailTime = 0;
const MIN_EMAIL_INTERVAL = 5 * 60 * 1000; // 5 minutes

function sendThrottledEmail(to, subject, message) {
  const now = Date.now();
  if (now - lastEmailTime > MIN_EMAIL_INTERVAL) {
    Android.sendAgentEmail(to, subject, message);
    lastEmailTime = now;
  }
}

Use for critical events only

Reserve emails for important events. Use speech or logs for routine updates.

// Email for critical errors
if (errorLevel === "critical") {
  Android.sendAgentEmail(/*...*/);
} else {
  // Just log or speak for minor issues
  Android.speakText("Minor error occurred");
}

Limitations

Requires configured backend email service
30-second timeout per request
No support for HTML emails (plain text only)
No attachment support
No delivery confirmation
Rate limiting depends on backend service

Troubleshooting

Email Not Sending

Check these common issues:

Backend not configured: Verify apiUrl points to valid endpoint
Security key mismatch: Ensure key matches backend
Network issues: Check device internet connection
Backend errors: Check backend logs

Testing

// Test email function
function testEmail() {
  Android.speakText("Testing email service");
  
  Android.sendAgentEmail(
    "your-email@example.com",
    "PhoneClaw Test Email",
    "This is a test message from PhoneClaw. If you receive this, email functionality is working correctly."
  );
  
  Android.delay(3000);
  Android.speakText("Check your inbox");
}

testEmail();

speakText() - Alternative notification method via TTS
schedule() - Schedule automated email reports
delay() - Add delays between multiple emails

ClawScript API

Helper Functions

Accessibility Service

sendAgentEmail()

Basic Usage

Practical Examples

Implementation Details

Source Location

Email Service

Configuration

Backend API Format

Complete Examples

Automation Report System

Multi-Recipient Notifications

Scheduled Reports

Best Practices

Limitations

Troubleshooting

Email Not Sending

Testing

​sendAgentEmail()

​Basic Usage

​Practical Examples

​Implementation Details

​Source Location

​Email Service

​Configuration

​Backend API Format

​Complete Examples

​Automation Report System

​Multi-Recipient Notifications

​Scheduled Reports

​Best Practices

​Limitations

​Troubleshooting

​Email Not Sending

​Testing

​Related Functions

sendAgentEmail()

Basic Usage

Practical Examples

Implementation Details

Source Location

Email Service

Configuration

Backend API Format

Complete Examples

Automation Report System

Multi-Recipient Notifications

Scheduled Reports

Best Practices

Limitations

Troubleshooting

Email Not Sending

Testing

Related Functions