Skip to main content
POST
/
api
/
automations
/
{id}
/
run
Run Automation
curl --request POST \
  --url https://api.example.com/api/automations/{id}/run
{
  "success": true,
  "processed": 123,
  "sent": 123,
  "skipped": 123,
  "failed": 123,
  "errors": [
    {}
  ],
  "message": "<string>",
  "timestamp": "<string>"
}

​
Run Automation

Manually execute a specific marketing automation. This endpoint is useful for testing automations or triggering them on-demand outside of scheduled cron jobs.

​
Endpoint

POST /api/automations/{id}/run

​
Authentication

Requires authenticated user session (no specific permission check).

​
Path Parameters

​
id
string
required
Automation ID (UUID)

​
Response

​
success
boolean
Whether the automation executed successfully
​
processed
number
Number of customers processed
​
sent
number
Number of messages sent successfully
​
skipped
number
Number of customers skipped (e.g., already contacted)
​
failed
number
Number of failed message attempts
​
errors
array
Array of error messages (if any)
​
message
string
Status message (e.g., “Automation is not active”)
​
timestamp
string
Execution timestamp (ISO 8601)

​
Example Request

curl -X POST https://your-domain.com/api/automations/123e4567-e89b-12d3-a456-426614174000/run \
  -H "Cookie: your-session-cookie"

​
Example Response (Success)

{
  "success": true,
  "processed": 45,
  "sent": 42,
  "skipped": 2,
  "failed": 1,
  "errors": [
    "Failed to send to +34612345678: Invalid phone number"
  ],
  "timestamp": "2026-03-04T10:30:00.000Z"
}

​
Example Response (Inactive Automation)

{
  "success": true,
  "message": "Automation is not active",
  "processed": 0,
  "sent": 0,
  "skipped": 0,
  "failed": 0,
  "timestamp": "2026-03-04T10:30:00.000Z"
}

​
Error Response

{
  "success": false,
  "error": "Automation not found",
  "timestamp": "2026-03-04T10:30:00.000Z"
}

​
400 Bad Request

{
  "error": "Automation ID is required",
  "timestamp": "2026-03-04T10:30:00.000Z"
}

​
Configuration

​
Timeout

The endpoint has an extended timeout for long-running automations: 
export const maxDuration = 300; // 5 minutes

​
Implementation Details

The endpoint calls the runAutomationCheck() server action: 
import { runAutomationCheck } from '@/app/actions/automations';

export async function POST(req: NextRequest, { params }: { params: Promise<{ id: string }> }) {
    const { id: automationId } = await params;
    const result = await runAutomationCheck(automationId);
    
    if (result.error) {
        return NextResponse.json({
            success: false,
            error: result.error,
            timestamp: new Date().toISOString()
        }, { status: 500 });
    }
    
    return NextResponse.json({
        success: true,
        processed: result.processed || 0,
        sent: result.sent || 0,
        skipped: result.skipped || 0,
        failed: result.failed || 0,
        errors: result.errors || [],
        timestamp: new Date().toISOString()
    });
}

​
Automation Execution Flow

  1. Validate Automation - Check if automation exists and is active
  2. Query Customers - Find customers matching automation criteria (e.g., inactive VIPs, birthdays)
  3. Filter Recipients - Skip customers recently contacted
  4. Send Messages - Send WhatsApp/SMS/Email via configured provider
  5. Log Results - Record execution results in automation_logs

​
Automation Types

Common automation triggers:
  • Inactive Customers - Re-engage customers who haven’t visited in X days
  • Birthday Campaigns - Send birthday messages and offers
  • VIP Rewards - Exclusive offers for VIP tier customers
  • Post-Visit Follow-up - Thank you messages after visits
  • Reservation Confirmations - Automated booking confirmations

​
Use Cases

  • Test automation logic before scheduling
  • Manually trigger campaign for immediate send
  • Re-run failed automation
  • Execute one-time campaigns

​
Logging

All executions are logged using the Logger service: 
logger.info("Automation executed successfully", "AutomationsAPI", {
    automationId,
    processed: result.processed,
    sent: result.sent,
    skipped: result.skipped,
    failed: result.failed
});
For scheduled automation execution, see Cron: Automations.
Manually running automations may send messages to customers. Use with caution in production environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us