mrkto — Marketo REST API CLI

Quick Reference

Run mrkto --help for the full command reference with all flags.

For Marketo-specific implementation notes and verified gotchas, read references/api-notes.md.

Setup

mrkto setup         # Interactive shortcut
mrkto auth setup    # Interactive — prompts for Munchkin ID, Client ID, Client Secret
mrkto auth check    # Verify credentials work
mrkto update        # Show the installer command as a dry run
mrkto update --execute
mrkto update --version vX.Y.Z --execute

If npx is available, the interactive mrkto setup flow may also offer to install the mrkto agent skill as an optional final step.

Profiles

• A profile is a saved Marketo connection
• Most users only need the default profile
• Create additional profiles when the same company has multiple Marketo instances, or when you need separate production and sandbox credentials
• Use names that describe the connection, like sandbox, marketing-prod, na, or emea
• --profile selects a saved connection explicitly
• .mrkto-profile lets a project directory automatically use the right connection

Examples:

mrkto auth setup --profile sandbox
mrkto auth check --profile sandbox
echo "sandbox" > .mrkto-profile

Common Workflows

Look up a lead by email

mrkto lead list --email [email protected]

Check unsubscribe / marketing suspended status

mrkto lead list --email [email protected] --fields id,email,unsubscribed,marketingSuspended,emailInvalid

Look up by SFDC ID

mrkto lead list --filter sfdcContactId=003xxxxxxxxxxxx
mrkto lead list --filter sfdcLeadId=00Qxxxxxxxxxxxx

Get lead's campaign and list membership

mrkto lead static-lists 12345
mrkto lead programs 12345
mrkto lead smart-campaigns 12345

Check activity history

mrkto activity list 12345 --since 90
mrkto activity list 12345 --type-id 11 --type-id 13
mrkto activity types

Activity pagination uses Marketo paging tokens. For activity endpoints, Adobe documents moreResult as the signal to continue; nextPageToken can still be present on the last page.

Watch field changes

mrkto activity changes --watch email --watch unsubscribed --since 7

Smart campaign operations

mrkto smart-campaign list --name "Welcome"
mrkto smart-campaign get 1234
mrkto smart-campaign trigger 1234 --lead 5001 --lead 5002 --execute

Static list operations

mrkto static-list list --name "Target"
mrkto static-list members 1234 --limit 50
mrkto static-list add 1234 --lead 5001 --lead 5002 --execute
mrkto static-list check 1234 --lead 5001 --lead 5002

Smart list operations

mrkto smart-list list --name "MQL"
mrkto smart-list get 1234

Company lookup

mrkto company list --name "ExtraHop"
mrkto company describe

Create a marketing folder

mrkto folder create "My Folder" --parent-id 1234
mrkto folder create "My Folder" --parent-id 1234 --execute

Email operations

mrkto email create "My Email" --template-id 1474 --folder-id 1234
mrkto email create "My Email" --template-id 1474 --folder-id 1234 --subject "New subject" --reply-to "[email protected]" --execute
mrkto email list --folder-id 1234 --folder-type Program --limit 20
mrkto email get 1234
mrkto email content get 1234
mrkto email content get 1234 --section freetext-v2-text
mrkto email update 1234 --subject "New subject" --reply-to "[email protected]"
mrkto email update 1234 --subject "New subject" --reply-to "[email protected]" --execute
mrkto email approve 1234 --execute
mrkto email discard-draft 1234 --execute

API stats

mrkto stats usage
mrkto stats errors --weekly

Raw API escape hatch

mrkto api get /v1/leads.json --query filterType=email --query [email protected]

Asset API (Email Programs, Emails, Folders)

The mrkto api escape hatch supports the full Marketo Asset API for managing programs, emails, folders, and templates.

Prefer mrkto folder create when you only need to create a marketing folder. Prefer mrkto email create|get|list|update|approve|discard-draft|content get for common email reads and lifecycle operations.

For Asset API mutations under /asset/, use --body for mutation fields. mrkto automatically sends those fields as application/x-www-form-urlencoded.

For the full list of verified Asset API, auth, and pagination gotchas, read references/api-notes.md.

Browse folder structure

mrkto api get /asset/v1/folder/937/content.json
mrkto api get /asset/v1/folder/1234.json

Programs

mrkto api get /asset/v1/program/1234.json
mrkto api post /asset/v1/program/1234/clone.json \
  --body 'name=My New Program' \
  --body 'folder={"id":5678,"type":"Folder"}'

Emails

# List emails in a program
mrkto api get /asset/v1/emails.json --query 'folder={"id":1234,"type":"Program"}'

# Get email metadata
mrkto api get /asset/v1/email/1234.json

# Get editable content sections
mrkto api get /asset/v1/email/1234/content.json

# Update one editable content section returned by /content.json
mrkto api post /asset/v1/email/1234/content/{{htmlId}}.json \
  --body 'type=Text' \
  --body 'value=<p>HTML content here</p>'

# Update email header fields (subject, from, reply-to)
mrkto api post /asset/v1/email/1234/content.json \
  --body 'subject={"type":"Text","value":"New subject"}' \
  --body 'fromName={"type":"Text","value":"Sender Name"}' \
  --body 'fromEmail={"type":"Text","value":"[email protected]"}' \
  --body 'replyTO={"type":"Text","value":"[email protected]"}'

Email templates

mrkto api get /asset/v1/emailTemplates.json --query 'maxReturn=10' --query 'status=approved'

Create marketing folders

mrkto api post /asset/v1/folders.json \
  --body 'name=My Folder' \
  --body 'parent={"id":1234,"type":"Folder"}'

Gotchas

• Asset API mutations use form bodies. For mrkto api post /asset/..., pass mutation fields with --body, not --query. The CLI sends Asset API mutation fields as application/x-www-form-urlencoded.

• Email header fields route to /content.json. The first-class mrkto email update command splits metadata fields and header fields automatically. If you use the raw API, subject, fromName, fromEmail, and replyTO belong on /asset/v1/email/{id}/content.json, not /asset/v1/email/{id}.json.

• Raw email create has a different field shape than email update. POST /asset/v1/emails.json accepts plain string fields for creation inputs, while mrkto email update uses typed header objects on /content.json. Prefer mrkto email create so the CLI can hide that split.

• Approved and draft email views are separate. After approving or editing an approved email, use mrkto email get <id> --status approved and mrkto email get <id> --status draft to inspect the exact version you mean. Marketo lifecycle changes can take a short time to settle.

• Email approval uses separate lifecycle endpoints. Adobe documents unapprove, approveDraft, and related email approval actions separately from content updates. When automating edits around approved assets, plan for explicit approval steps:

  mrkto api post /asset/v1/email/1234/unapprove.json   # → draft
  mrkto api post /asset/v1/email/1234/content.json --body '...' # update header fields
  mrkto api post /asset/v1/email/1234/approveDraft.json  # → approved
  

  The exact editability rules vary by endpoint, so verify the approval state your workflow expects.

• Smart list filter editing is not documented in the Asset API. Adobe documents query, clone, and delete operations for smart lists, but not filter-rule editing endpoints. Expect filter rules to require the Marketo UI unless Adobe documents an API path for your use case.

• Asset browse endpoints page with offset and maxReturn. Adobe documents maxReturn up to 200 for asset browsing. Use those parameters when walking large result sets.

• Folder content vs. folder details are separate endpoints. /folder/{id}.json returns the folder's own metadata. /folder/{id}/content.json returns its children (programs, sub-folders).

Key Conventions

• The CLI uses singular resource nouns with explicit Marketo concepts like smart-campaign, static-list, and smart-list
• Structured output flags are --json, --compact, and --raw
• Write operations (schedule, trigger, add, remove) require --execute — without it they dry-run
• --filter key=value is the escape hatch for lead and company filters not promoted to a named flag
• Lead default fields: id, email, firstName, lastName, company, unsubscribed, marketingSuspended, emailInvalid, sfdcLeadId, sfdcContactId, createdAt, updatedAt
• Use mrkto lead describe to discover all available lead fields