Smart Defaults - Cakemail

Learn how the CLI automatically detects resources to streamline your workflow.

Overview

Smart Defaults (introduced) eliminate repetitive parameter inputs by auto-detecting common resources like lists and senders. If you have only one list or one confirmed sender, the CLI automatically uses it - no need to specify IDs every time!

Key Benefits:

Zero-configuration workflow for users with single lists
Fewer command-line parameters to remember
Session caching for fast repeated operations
Helpful suggestions when multiple resources exist

How Auto-Detection Works

When a command needs a list ID or sender ID, the CLI:

Checks if parameter was provided - If you specified --list-id, it uses that
Looks in session cache - Recent API calls are cached for 5 minutes
Fetches from API - If not cached, makes API call to list resources
Auto-detects single resource - If exactly one exists, uses it automatically
Prompts or errors - If multiple exist, shows options (interactive) or error (batch)

Commands with Auto-Detection

List Auto-Detection (14 commands)

These commands make list-id optional when you have exactly one list:

Contact Management:

contacts list [list-id] - List contacts
contacts add [list-id] - Add contact
contacts export [list-id] - Export contacts
contacts exports [list-id] - List exports

Segments:

segments list [list-id] - List segments
segments get [list-id] <segment-id> - Get segment
segments create [list-id] - Create segment
segments update [list-id] <segment-id> - Update segment
segments delete [list-id] <segment-id> - Delete segment
segments contacts [list-id] <segment-id> - List segment contacts

Custom Attributes:

attributes list [list-id] - List attributes
attributes get [list-id] <name> - Get attribute
attributes create [list-id] - Create attribute
attributes delete [list-id] <name> - Delete attribute

Sender Auto-Detection (1 command)

This command makes sender-id optional when you have exactly one confirmed sender:

campaigns create - Auto-detects both list ID and sender ID

Single Resource Scenario

When you have exactly one list (or sender), the CLI uses it automatically.

Example: List Contacts (Single List)

$ cakemail contacts list

Output:

✓ Auto-detected list: 123 (Newsletter Subscribers)

┌──────────────────────┬────────────────────┬──────────────┐
│ Email                │ Status             │ Subscribed   │
├──────────────────────┼────────────────────┼──────────────┤
│ john@example.com     │ ✓ active           │ 2 days ago   │
│ jane@example.com     │ ✓ active           │ 5 days ago   │
└──────────────────────┴────────────────────┴──────────────┘

What Happened:

No --list-id provided
CLI fetched lists from API
Found exactly one list (ID: 123)
Used it automatically
Shows confirmation message

Multiple Resources Scenario

When multiple lists exist, behavior depends on your profile and environment.

Interactive Mode (Marketer/Balanced Profiles in TTY)

The CLI shows an interactive selection menu:

$ cakemail contacts list

Output:

Multiple lists found. Please select one:

? Select a list:
  ❯ Newsletter Subscribers (1,234 contacts)
    Product Updates (567 contacts)
    VIP Customers (89 contacts)

After selection, command proceeds with chosen list.

Non-Interactive Mode (Developer Profile or Scripts)

The CLI returns an error with suggestions:

$ cakemail contacts list

Output:

Error: Multiple lists found. Please specify --list-id <id>

Available lists:
  123: Newsletter Subscribers (1,234 contacts)
  456: Product Updates (567 contacts)
  789: VIP Customers (89 contacts)

Example:
  cakemail contacts list --list-id 123

Solution: Provide --list-id:

cakemail contacts list --list-id 123

Session Caching

To improve performance, the CLI caches resource lookups for 5 minutes.

How It Works:

First call fetches lists from API
Result cached in memory
Subsequent calls within 5 minutes use cache
Cache expires after 5 minutes

Example:

# First call - fetches from API
$ cakemail contacts list
✓ Auto-detected list: 123

# Second call within 5 minutes - uses cache (instant)
$ cakemail segments list
✓ Auto-detected list: 123

# Third call within 5 minutes - uses cache (instant)
$ cakemail attributes list
✓ Auto-detected list: 123

Benefits:

Faster command execution
Reduced API calls
Better user experience
Lower API rate limit usage

Cache Scope:

Per CLI session (process)
Not persisted to disk
Cleared after 5 minutes
Separate for lists and senders

Sender Auto-Detection

The campaigns create command auto-detects senders, but only confirmed ones.

Single Confirmed Sender

$ cakemail campaigns create --name "Weekly Newsletter" --list-id 123

Output:

✓ Auto-detected sender: 456 (Marketing Team <marketing@company.com>)
✓ Campaign created: 789

Multiple Confirmed Senders (Interactive)

$ cakemail campaigns create --name "Weekly Newsletter" --list-id 123

Output:

? Select a sender:
  ❯ Marketing Team <marketing@company.com> (Confirmed)
    Sales Team <sales@company.com> (Confirmed)
    Support <support@company.com> (Confirmed)

No Confirmed Senders

$ cakemail campaigns create --name "Weekly Newsletter" --list-id 123

Output:

Error: No confirmed senders found. Please verify a sender first.

To create a sender:
  cakemail senders create --name "Marketing Team" --email "marketing@company.com"

Then confirm via the email link sent to the sender address.

Note: Only confirmed senders are considered for auto-detection. Pending senders are excluded.

Disabling Auto-Detection

If you want to explicitly provide IDs every time, you have options:

Option 1: Always Provide Parameters

cakemail contacts list --list-id 123
cakemail segments create --list-id 123 --name "Active Users"

Option 2: Use Developer Profile

Developer profile skips interactive prompts:

cakemail config profile-set developer
cakemail contacts list  # Error if list-id not provided

Option 3: Use Batch Mode

cakemail --batch contacts list --list-id 123

Best Practices

1. Let Auto-Detection Work

For single-list users, embrace auto-detection:

# Good - simple and clear
cakemail contacts list

# Unnecessary - adds extra typing
cakemail contacts list --list-id 123

2. Provide IDs in Scripts

In automation, always provide IDs explicitly:

#!/bin/bash
# Good - explicit and reliable
cakemail contacts export --list-id 123

# Avoid - depends on account state
cakemail contacts export

3. Use Cache for Repeated Operations

Group related commands together to benefit from caching:

# These all use the cached list lookup
cakemail contacts list
cakemail segments list
cakemail attributes list

4. Profile-Aware Workflows

Choose profile based on your needs:

Marketer: Interactive prompts when multiple resources exist
Balanced: Interactive in terminal, error in scripts
Developer: Always require explicit IDs

Troubleshooting

"Multiple lists found" Error

Problem: Getting error even though you want to use a specific list

Solution: Provide --list-id:

cakemail contacts list --list-id 123

Or switch to interactive profile:

cakemail config profile-set marketer
cakemail contacts list  # Will show selection menu

Auto-Detection Not Working

Problem: CLI asks for list-id even though you have only one list

Solutions:

Check you actually have lists:
```
cakemail lists list
```

Verify the parameter name:

# Correct
cakemail contacts list

# Wrong - this command doesn't support auto-detection
cakemail lists get --list-id 123  # 'list-id' is required parameter here

Clear and retry: Sometimes caching issues occur. Start a new terminal session.

Unwanted Interactive Prompts

Problem: Getting prompts in scripts

Solutions:

Use batch mode:

cakemail --batch contacts list --list-id 123

Switch to developer profile:
```
cakemail config profile-set developer
```

Always provide parameters:

cakemail contacts list --list-id 123 --limit 100

Commands That Don't Support Auto-Detection

These commands always require explicit IDs:

Resource-Specific Operations:

lists get <id> - Specific list required
lists update <id> - Specific list required
lists delete <id> - Specific list required
campaigns get <id> - Specific campaign required
senders get <id> - Specific sender required

Reason: These operate on a specific resource, not a default one.

Examples

Example 1: Quick Contact Export

Scenario: Export contacts from your only list

# Old way (without smart defaults)
cakemail lists list  # Find list ID
cakemail contacts export --list-id 123

# New way
cakemail contacts export
# ✓ Auto-detected list: 123 (Newsletter Subscribers)
# ✓ Export created: 456

Example 2: Create Segment Workflow

Scenario: Create and populate a segment

# All these commands use the same cached list
cakemail segments create --name "Active Users" --conditions "status==active"
# ✓ Auto-detected list: 123

cakemail segments list
# ✓ Auto-detected list: 123 (cached)

cakemail segments contacts 789
# ✓ Auto-detected list: 123 (cached)

Example 3: Multi-List Account

Scenario: Working with multiple lists interactively

# Marketer profile enables interactive selection
cakemail config profile-set marketer

cakemail contacts list
# ? Select a list:
#   ❯ Newsletter (1,234 contacts)
#     Product Updates (567 contacts)

# Choose "Newsletter" from menu
# [Shows Newsletter contacts]

cakemail segments list
# ? Select a list:
#   ❯ Newsletter (1,234 contacts)
#     Product Updates (567 contacts)

# Choose "Newsletter" again
# [Shows Newsletter segments]

Example 4: Scripted Multi-List Operations

Scenario: Script that works with specific lists

#!/bin/bash
# Always provide list-id in scripts

NEWSLETTER_LIST=123
PRODUCT_LIST=456

# Export from both lists
cakemail contacts export --list-id $NEWSLETTER_LIST
cakemail contacts export --list-id $PRODUCT_LIST

echo "Exports created for both lists"

Related Features

Smart Defaults work together with other CLI features:

Profile System - Controls interactive vs non-interactive behavior
Interactive Prompts - Shows selection menus in interactive mode
Batch Mode - Disables all auto-detection prompts