Preview: SendMock has no stable release yet. These docs follow develop.

CLI reference

Email providers commands

sendmock email providers create

Add an email provider, blank or copied from another.

sendmock email providers create [flags]
FlagTypeDescription
--name <name>requiredstring
The new provider's name.Example: SSL Wireless
--key <key>requiredstring
Its key in /providers/<key>/... paths and on messages; lowercase, fixed after creation.Example: sslwireless
--start-from <start-from>string
A provider of the same area to copy, or null to start blank.Example: twilio

Example

sendmock email providers create --name 'SSL Wireless' --key sslwireless --start-from twilio

Output with --json: MessageProviderDefinition. Exit codes: 0, 1, 2.

API
POST/api/v1/emails/providers
MCP tool
sendmock_email_provider_create
In the app
Mail > Providers > Add provider

sendmock email providers credential

Reveal one secret credential (asked for after a confirmation).

sendmock email providers credential <providerKey> <credentialName> --reveal
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio
<credentialName>requiredstring
The credential's name in the gateway or provider, e.g. secret_key or api_key.Example: secret_key
FlagTypeDescription
--revealboolean
Prints the secret in plain text instead of masked.

Example

sendmock email providers credential twilio secret_key --reveal

Output with --json: ProviderCredentialReveal. Exit codes: 0, 1, 2, 3.

API
GET/api/v1/emails/providers/{providerKey}/credentials/{credentialName}
In the app
Mail > Providers > provider > General > Reveal

sendmock email providers delete

Remove a built-in (restorable) or delete a custom provider; its messages stay.

sendmock email providers delete <providerKey> [flags]
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio
FlagTypeDescription
--yesboolean
Confirms a destructive command; without it the command stops.

Example

sendmock email providers delete twilio --yes

Output with --json: nothing. Exit codes: 0, 1, 2, 3.

API
DELETE/api/v1/emails/providers/{providerKey}
MCP tool
sendmock_email_provider_delete
In the app
Mail > Providers > provider > Remove or Delete

sendmock email providers preview

Run a sample request through a definition: the message it would store and the answer it would give.

sendmock email providers preview <providerKey> [flags]
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio
FlagTypeDescription
--provider <provider>requiredMessageProviderInput (JSON)
The provider settings to run, saved or not.
--sample-request <sample-request>ProviderSampleRequest (JSON)
The request to run; the provider's example send when left out.

Example

sendmock email providers preview twilio --provider '{"key":"sendgrid","name":"SendGrid","accent":"#1a82e2","is_enabled":true,"host":"api.sendgrid.com","credentials":[{"name":"api_key","value":"SG.test_key_123","is_secret":true}],"check_credentials":false,"operations":[{"kind":"send","method":"POST","path":"/v3/{domain}/messages","request_format":"multipart"}],"field_mapping":[{"part":"to","source":"personalizations[0].to[*].email"}],"validation_rules":[{"part":"to","check":"required","max_length":null,"error_kind":"missing_field"}],"success_response":{"status":202,"headers":[{"name":"X-Message-Id","template":"{{ message.provider_id }}"}],"body":"{\"id\": \"{{ message.provider_id }}\"}"},"error_responses":[{"kind":"missing_field","status":202,"headers":[{"name":"X-Message-Id","template":"{{ message.provider_id }}"}],"body":"{\"id\": \"{{ message.provider_id }}\"}"}],"message_id_template":"<{{ uuid() }}@sendmock.local>","callback_template_key":"sendgrid-event","status_names":{"delivered":"delivered","bounced":"bounce","complained":"spamreport"},"outcome_error_codes":{"invalid_number":"21211","unreachable":"30003"}}'

Output with --json: MessageProviderPreview. Exit codes: 0, 1, 2, 3.

API
POST/api/v1/emails/providers/{providerKey}/preview
MCP tool
sendmock_email_provider_preview
In the app
Mail > Providers > provider > Preview

sendmock email providers reset

Put a built-in provider back as shipped.

sendmock email providers reset <providerKey>
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio

Example

sendmock email providers reset twilio

Output with --json: MessageProviderDefinition. Exit codes: 0, 1, 2, 3.

API
POST/api/v1/emails/providers/{providerKey}/reset
MCP tool
sendmock_email_provider_reset
In the app
Mail > Providers > provider > Reset to default

sendmock email providers restore

Bring a removed built-in back as it was.

sendmock email providers restore <providerKey>
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio

Example

sendmock email providers restore twilio

Output with --json: MessageProviderDefinition. Exit codes: 0, 1, 2, 3.

API
POST/api/v1/emails/providers/{providerKey}/restore
MCP tool
sendmock_email_provider_restore
In the app
Mail > Providers > Removed > Restore

sendmock email providers show

One provider definition; secret credentials masked.

sendmock email providers show <providerKey>
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio

Example

sendmock email providers show twilio

Output with --json: MessageProviderDefinition. Exit codes: 0, 1, 2, 3.

API
GET/api/v1/emails/providers/{providerKey}
MCP tool
sendmock_email_provider_get
In the app
Mail > Providers > provider

sendmock email providers update

Change a provider; 400 with the problems for template errors, bad paths or a path clash.

sendmock email providers update <providerKey> [flags]
ArgumentTypeDescription
<providerKey>requiredstring
The email or SMS provider's key, e.g. sendgrid or twilio, from its providers list.Example: twilio
FlagTypeDescription
--key <key>requiredstring
The /providers/<key>/... path and the provider value stored on each message; lowercase, fixed after creation.Example: sendgrid
--name <name>requiredstring
The provider's name, shown on messages and in pickers.Example: SendGrid
--accent <accent>requiredstring
#rrggbb, used on its badge.Example: #1a82e2
--enabledrequiredboolean
Off providers answer nothing; their paths get SendMock's native 404. --no-enabled sets it to false.
--host <host>string
The provider's API host, used on the provider port to tell apart providers that share a path; null when not needed.Example: api.sendgrid.com
--credentials <credentials>requiredProviderCredential[] (JSON)
The credentials your app is configured with.Example: [{"name":"api_key","value":"SG.test_key_123","is_secret":true}]
--check-credentialsrequiredboolean
Off by default: any credentials are accepted. On: wrong ones get the provider's unauthorized answer. --no-check-credentials sets it to false.
--operations <operations>requiredProviderOperation[] (JSON)
The requests it answers.Example: [{"kind":"send","method":"POST","path":"/v3/{domain}/messages","request_format":"multipart"}]
--field-mapping <field-mapping>requiredProviderFieldMapping[] (JSON)
Where each part of a sent message is read from; anything else is kept as metadata.Example: [{"part":"to","source":"personalizations[0].to[*].email"}]
--validation-rules <validation-rules>requiredProviderValidationRule[] (JSON)
The checks run on each send, in order.Example: [{"part":"to","check":"required","max_length":null,"error_kind":"missing_field"}]
--success-response <success-response>requiredProviderResponseTemplate (JSON)
The answer to a request that passes every check.
--error-responses <error-responses>requiredProviderErrorResponse[] (JSON)
The answer for each kind of error.Example: [{"kind":"missing_field","status":202,"headers":[{"name":"X-Message-Id","template":"{{ message.provider_id }}"}],"body":"{\"id\": \"{{ message.provider_id }}\"}"}]
--message-id-template <message-id-template>requiredstring
The provider's id for each message, a template.Example: <{{ uuid() }}@sendmock.local>
--callback-template-key <callback-template-key>string
The webhook template its status callbacks and inbound messages are sent with; null sends none.Example: sendgrid-event
--status-names <status-names>requiredobject (JSON)
The provider's name for each SendMock status.
--outcome-error-codes <outcome-error-codes>requiredobject (JSON)
SMS only: the provider's error code for each delivery outcome, so test numbers fail with its own codes.

Example

sendmock email providers update twilio --key sendgrid --name SendGrid --accent '#1a82e2' --enabled --credentials '[{"name":"api_key","value":"SG.test_key_123","is_secret":true}]' --no-check-credentials --operations '[{"kind":"send","method":"POST","path":"/v3/{domain}/messages","request_format":"multipart"}]' --field-mapping '[{"part":"to","source":"personalizations[0].to[*].email"}]' --validation-rules '[{"part":"to","check":"required","max_length":null,"error_kind":"missing_field"}]' --success-response '{"status":202,"headers":[{"name":"X-Message-Id","template":"{{ message.provider_id }}"}],"body":"{\"id\": \"{{ message.provider_id }}\"}"}' --error-responses '[{"kind":"missing_field","status":202,"headers":[{"name":"X-Message-Id","template":"{{ message.provider_id }}"}],"body":"{\"id\": \"{{ message.provider_id }}\"}"}]' --message-id-template '<{{ uuid() }}@sendmock.local>' --status-names '{"delivered":"delivered","bounced":"bounce","complained":"spamreport"}' --outcome-error-codes '{"invalid_number":"21211","unreachable":"30003"}' --host api.sendgrid.com --callback-template-key sendgrid-event

Output with --json: MessageProviderDefinition. Exit codes: 0, 1, 2, 3.

API
PATCH/api/v1/emails/providers/{providerKey}
MCP tool
sendmock_email_provider_update
In the app
Mail > Providers > provider > Save provider