---
updatedAt: 2026-06-08T12:06:26.000Z
agentTools:
  projectIndex: https://salesautopilot.readme.io/llms.txt
---

# Create a new letter

Creates a new letter in the system with HTML content and optional configuration.

## Default Behavior
- If `linkTrackingEnabled` is not provided, it defaults to `true`
- If `linkTrackingEnabled` is `true` and no `linkTrackingDomain` is provided, validation will fail
- If `textContent` is not provided, it will be automatically generated from the HTML content by stripping tags
- If `folderId` is not provided or set to `0`, the letter will be created in the default folder
- If `openTrackingEnabled` is not provided, it defaults to `false`
- If `googleAnalyticsEnabled` is not provided, it defaults to `false`

## Tracking Configuration
Configure link and open tracking to monitor recipient engagement:
- **Link tracking**: Track clicks on links in your email (requires a valid tracking domain)
- **Open tracking**: Track when recipients open your email
- **Google Analytics**: Append GA tracking parameters to links


# OpenAPI definition

````json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Mailing",
    "version": "2.0.0",
    "description": "The Mailing API allows you to manage letters, folders, and email sends in the SalesAutopilot platform.\n\n## Features\n\n### Letters\n- Create new letters with HTML and optional text content\n- Update existing letters (partial updates supported)\n- Delete letters from the system\n- Configure link tracking with custom domains\n- Enable/disable open tracking\n- Integrate with Google Analytics\n- Organize letters in folders\n\n### Letter Folders\n- Create new letter folders\n- Update folder names and project assignments\n- Delete folders (letters are automatically moved to default folder)\n- Organize folders within project folders\n\n### Sends\n- Create new email sends with different sending types\n- Update existing send configurations\n- Retrieve send details\n- Delete sends\n- Send test emails to specific subscribers\n- Support for absolute and relative sending schedules\n- Smart Send functionality for optimized sending times\n- Subscription and data update triggered sends\n\n## Send Types\n- **ABSOLUTE**: Send at a specific date and time\n- **SMART_SEND**: Send on a specific date using AI-optimized times per subscriber\n- **RELATIVE_AFTER_DATE**: Send relative to a date field with day/hour/minute precision\n- **RELATIVE_AFTER_MINUTES**: Send relative to a field after specified hours and minutes\n- **SUBSCRIPTION**: Trigger on subscription (can be filtered by form)\n- **DATA_UPDATE**: Trigger on data modification (can be filtered by form)\n\n## Authentication\nAll API requests require authentication. Use [Authentication](https://salesautopilot.readme.io/reference/login) to obtain a JWT Bearer token, or use **HTTP Basic** with the same API username and password (`Authorization: Basic …`).\n",
    "contact": {
      "name": "SalesAutopilot Support",
      "url": "https://support.salesautopilot.com"
    },
    "termsOfService": "https://salesautopilot.com/terms"
  },
  "servers": [
    {
      "url": "https://api.salesautopilot.com/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "Letters",
      "description": "Manage letters for your campaigns"
    }
  ],
  "paths": {
    "/letters": {
      "post": {
        "tags": [
          "Letters"
        ],
        "summary": "Create a new letter",
        "description": "Creates a new letter in the system with HTML content and optional configuration.\n\n## Default Behavior\n- If `linkTrackingEnabled` is not provided, it defaults to `true`\n- If `linkTrackingEnabled` is `true` and no `linkTrackingDomain` is provided, validation will fail\n- If `textContent` is not provided, it will be automatically generated from the HTML content by stripping tags\n- If `folderId` is not provided or set to `0`, the letter will be created in the default folder\n- If `openTrackingEnabled` is not provided, it defaults to `false`\n- If `googleAnalyticsEnabled` is not provided, it defaults to `false`\n\n## Tracking Configuration\nConfigure link and open tracking to monitor recipient engagement:\n- **Link tracking**: Track clicks on links in your email (requires a valid tracking domain)\n- **Open tracking**: Track when recipients open your email\n- **Google Analytics**: Append GA tracking parameters to links\n",
        "operationId": "createLetter",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name/title of the letter (cannot be empty)",
                    "example": "Welcome Email Campaign",
                    "minLength": 1
                  },
                  "htmlContent": {
                    "type": "string",
                    "description": "The HTML content of the email. Either htmlContent or htmlContentUrl is required, but not both.\n",
                    "example": "<html><body><h1>Welcome!</h1><p>Thank you for subscribing.</p></body></html>",
                    "minLength": 1
                  },
                  "htmlContentUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Alternative to htmlContent: a publicly reachable HTTPS URL the server fetches the HTML content from server-side. Use this to upload large or externally-authored HTML verbatim without including it in the request body. Either htmlContent or htmlContentUrl is required, but not both. The URL must resolve to a public, non-private IP address; the fetched content is capped at 2MB.\n",
                    "example": "https://example.com/letters/welcome.html"
                  },
                  "textContent": {
                    "type": "string",
                    "description": "Plain text version of the email (optional, will be auto-generated from HTML if not provided)",
                    "example": "Welcome!\n\nThank you for subscribing."
                  },
                  "folderId": {
                    "type": "integer",
                    "description": "The ID of the folder to store the letter in (0 or null for default folder)",
                    "example": 456,
                    "default": 0
                  },
                  "linkTrackingEnabled": {
                    "type": "boolean",
                    "description": "Enable click tracking for links in the email",
                    "example": true,
                    "default": true
                  },
                  "linkTrackingDomain": {
                    "type": "string",
                    "description": "The subdomain to use for link tracking (required if linkTrackingEnabled is true)",
                    "example": "track.example.com"
                  },
                  "openTrackingEnabled": {
                    "type": "boolean",
                    "description": "Enable open tracking to monitor when recipients open the email",
                    "example": true,
                    "default": false
                  },
                  "googleAnalyticsEnabled": {
                    "type": "boolean",
                    "description": "Enable Google Analytics tracking parameters on links",
                    "example": false,
                    "default": false
                  },
                  "projectFolderId": {
                    "type": "integer",
                    "description": "The ID of the project folder (optional)",
                    "example": 789
                  }
                }
              },
              "examples": {
                "minimal": {
                  "summary": "Minimal required fields",
                  "value": {
                    "name": "Welcome Email",
                    "htmlContent": "<html><body><h1>Welcome!</h1></body></html>",
                    "linkTrackingEnabled": false
                  }
                },
                "withTracking": {
                  "summary": "With link and open tracking",
                  "value": {
                    "name": "Newsletter January 2026",
                    "htmlContent": "<html><body><h1>January Newsletter</h1><p>Check out our latest updates.</p></body></html>",
                    "textContent": "January Newsletter\n\nCheck out our latest updates.",
                    "linkTrackingEnabled": true,
                    "linkTrackingDomain": "track.example.com",
                    "openTrackingEnabled": true
                  }
                },
                "complete": {
                  "summary": "All fields specified",
                  "value": {
                    "name": "Product Launch Campaign",
                    "htmlContent": "<html><body><h1>New Product Launch</h1><p>Discover our latest product.</p></body></html>",
                    "textContent": "New Product Launch\n\nDiscover our latest product.",
                    "folderId": 456,
                    "linkTrackingEnabled": true,
                    "linkTrackingDomain": "track.example.com",
                    "openTrackingEnabled": true,
                    "googleAnalyticsEnabled": true,
                    "projectFolderId": 789
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Letter created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Letter"
                    }
                  }
                },
                "examples": {
                  "success": {
                    "summary": "Successful creation",
                    "value": {
                      "success": true,
                      "data": {
                        "id": 123,
                        "name": "Welcome Email Campaign",
                        "folderId": 456,
                        "htmlContent": "<html><body><h1>Welcome!</h1></body></html>",
                        "textContent": "Welcome!",
                        "linkTrackingEnabled": true,
                        "linkTrackingDomain": "track.example.com",
                        "openTrackingEnabled": true,
                        "googleAnalyticsEnabled": false,
                        "createdAt": "2026-01-22T10:00:00+00:00",
                        "updatedAt": "2026-01-22T10:00:00+00:00"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missingName": {
                    "summary": "Missing required field - name",
                    "value": {
                      "error": "Missing required field: name",
                      "code": 14001
                    }
                  },
                  "missingHtmlContent": {
                    "summary": "Missing required field - htmlContent",
                    "value": {
                      "error": "Missing required field: htmlContent",
                      "code": 14002
                    }
                  },
                  "invalidFolder": {
                    "summary": "Invalid folder ID",
                    "value": {
                      "error": "Invalid folder ID",
                      "code": 14003
                    }
                  },
                  "linkTrackingDomainRequired": {
                    "summary": "Link tracking domain required",
                    "value": {
                      "error": "Link tracking domain is required when link tracking is enabled",
                      "code": 14004
                    }
                  },
                  "invalidLinkTrackingDomain": {
                    "summary": "Invalid link tracking domain",
                    "value": {
                      "error": "Invalid link tracking domain",
                      "code": 14005
                    }
                  },
                  "invalidHtmlContentUrl": {
                    "summary": "htmlContentUrl is not a valid or reachable URL",
                    "value": {
                      "error": "htmlContentUrl must be a valid https:// URL",
                      "code": 14007
                    }
                  },
                  "htmlContentConflict": {
                    "summary": "Both htmlContent and htmlContentUrl provided",
                    "value": {
                      "error": "Provide either htmlContent or htmlContentUrl, not both",
                      "code": 14008
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT token obtained from the [/access-token endpoint](https://salesautopilot.readme.io/reference/login).\n\nInclude the token in the Authorization header:\n```\nAuthorization: Bearer YOUR_JWT_TOKEN\n```\n"
      },
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic authentication using your API username and password.\n```\nAuthorization: Basic BASE64(username:password)\n```\n"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Error message"
          },
          "code": {
            "type": "integer",
            "description": "Error code for programmatic handling",
            "example": 10000
          }
        }
      },
      "Letter": {
        "type": "object",
        "required": [
          "id",
          "name",
          "htmlContent",
          "linkTrackingEnabled",
          "openTrackingEnabled",
          "googleAnalyticsEnabled"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique identifier of the letter",
            "example": 123
          },
          "name": {
            "type": "string",
            "description": "The name/title of the letter",
            "example": "Welcome Email Campaign"
          },
          "folderId": {
            "type": "integer",
            "nullable": true,
            "description": "The ID of the folder containing the letter (null for default folder)",
            "example": 456
          },
          "projectFolderId": {
            "type": "integer",
            "description": "The project folder this letter belongs to (0 for the default/root folder)",
            "example": 42
          },
          "htmlContent": {
            "type": "string",
            "description": "The HTML content of the email",
            "example": "<html><body><h1>Welcome!</h1></body></html>"
          },
          "textContent": {
            "type": "string",
            "description": "The plain text version of the email",
            "example": "Welcome!"
          },
          "hasDraft": {
            "type": "boolean",
            "description": "Whether the letter currently has an unsaved draft version being edited. False means the displayed htmlContent/textContent is the last published version.",
            "example": false
          },
          "linkTrackingEnabled": {
            "type": "boolean",
            "description": "Whether link tracking is enabled",
            "example": true
          },
          "linkTrackingDomain": {
            "type": "string",
            "nullable": true,
            "description": "The subdomain used for link tracking (null if not configured)",
            "example": "track.example.com"
          },
          "openTrackingEnabled": {
            "type": "boolean",
            "description": "Whether open tracking is enabled",
            "example": true
          },
          "googleAnalyticsEnabled": {
            "type": "boolean",
            "description": "Whether Google Analytics tracking is enabled",
            "example": false
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date and time when the letter was created (ISO 8601 format)",
            "example": "2026-01-22T10:00:00+00:00"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date and time when the letter was last updated (ISO 8601 format)",
            "example": "2026-01-22T12:30:00+00:00"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid authentication token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "unauthorized": {
                "summary": "Authentication required",
                "value": {
                  "error": "Unauthorized",
                  "code": 401
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "rateLimited": {
                "summary": "Too many requests",
                "value": {
                  "error": "Too many requests. Please wait before making another request to this endpoint.",
                  "code": 429
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "serverError": {
                "summary": "Server error",
                "value": {
                  "error": "Internal server error",
                  "code": 500
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "samples-languages": [
      "curl",
      "php",
      "javascript",
      "python"
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
````