POST /execute | Docs

Overview

The /execute endpoint runs the flow configured for a template. Depending on your flow configuration, this can:

Render the template and return HTML (callback output)
Validate inputs and send via your configured provider (provider output)

Endpoint

POST /v1/execute

Request Body

Field	Type	Required	Description
`templateId`	string	Yes	The template to execute
`variables`	object	Yes	Variables to hydrate the template
`_to`	string	Conditional	Recipient email (required for provider output)
`_subject`	string	No	Override the template subject
`_replyTo`	string	No	Reply-to email address
`_cc`	string	No	CC recipients (comma-separated)
`_bcc`	string	No	BCC recipients (comma-separated)

Fields prefixed with _ are reserved for email delivery configuration.

Example Request

curl -X POST https://api.mailsh.it/v1/execute \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_abc123",
    "variables": {
      "firstName": "Alice",
      "orderNumber": "12345"
    },
    "_to": "alice@example.com",
    "_subject": "Your order has shipped!"
  }'

Response Types

The response depends on your flow configuration.

Sent (Provider Output)

When the flow includes a provider output node and the email is sent successfully:

{
  "success": true,
  "type": "sent",
  "messageId": "msg_abc123xyz"
}

Callback (No Provider)

When the flow uses a callback output or has no output node:

{
  "success": true,
  "type": "callback",
  "html": "<!DOCTYPE html><html>...</html>",
  "text": "Plain text version...",
  "subject": "Your order has shipped!"
}

Validation Failed

When a verification node fails:

{
  "success": false,
  "type": "validation_failed",
  "error": "Invalid email address",
  "field": "_to"
}

Send Failed

When the email provider returns an error:

{
  "success": false,
  "type": "send_failed",
  "error": "Recipient email is not verified"
}

Flow Error

When there’s a configuration issue:

{
  "success": false,
  "type": "flow_error",
  "error": "Template not found in flow graph"
}

Flow Node Types

Your flow can include these node types:

Node Type	Description
Template	The email template to render
Variables	Inputs connected to the template
Provider Output	Sends via your email provider
Callback Output	Returns HTML without sending
Verification	Validates inputs before proceeding

Verification Types

If your flow includes verification nodes, they run before sending:

Email Domain Verification

Validates the _to address format and domain MX records.

Required Fields

Ensures specified variables are provided and non-empty.

Custom Regex

Validates a variable against a regular expression pattern.

Code Examples

JavaScript

async function sendWelcomeEmail(email: string, name: string) {
  const response = await fetch('https://api.mailsh.it/v1/execute', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MAILSHIT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      templateId: 'tmpl_welcome',
      variables: { name },
      _to: email,
    }),
  })

  const result = await response.json()

  if (result.success && result.type === 'sent') {
    console.log('Email sent:', result.messageId)
  } else if (!result.success) {
    console.error('Failed:', result.error)
  }

  return result
}

Python

def send_welcome_email(email: str, name: str):
    response = requests.post(
        'https://api.mailsh.it/v1/execute',
        headers={
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
        },
        json={
            'templateId': 'tmpl_welcome',
            'variables': {'name': name},
            '_to': email,
        },
    )

    result = response.json()

    if result.get('success') and result.get('type') == 'sent':
        print(f"Email sent: {result['messageId']}")
    elif not result.get('success'):
        print(f"Failed: {result['error']}")

    return result

Best Practices

Always check success - Don’t assume emails were sent
Handle all response types - Your flow configuration determines the response
Log messageIds - Useful for debugging delivery issues
Use verification nodes - Catch invalid inputs before sending