> ## Documentation Index > Fetch the complete documentation index at: https://docs.maildiver.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Send email > **Endpoint:** `v1/emails` Send a transactional email with optional template, attachments, and variables ## OpenAPI ````yaml api-reference/openapi.yml post /emails openapi: 3.1.0 info: title: Send Email API description: > Send transactional emails through MailDiver. ### Base URL All API endpoints are prefixed with `api.` subdomain: ``` https://api.maildiver.com ``` For the self-hosted version, if your domain is `example.com`: ``` https://api.example.com ``` ### Endpoint ``` v1/emails ``` ### Authentication All API requests require authentication using your API key in the Authorization header: ``` Authorization: Bearer your-api-key ``` version: 1.0.0 license: name: MIT servers: - url: https://api.maildiver.com/v1 description: Production server variables: domain: default: yourdomain.com description: Your domain (without the api. prefix) security: - bearerAuth: [] paths: /emails: post: tags: - Email summary: Send email description: > **Endpoint:** `v1/emails` Send a transactional email with optional template, attachments, and variables operationId: sendEmail requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendEmailRequest' responses: '201': description: Email successfully queued for sending content: application/json: schema: $ref: '#/components/schemas/SendEmailResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden (API key is missing or invalid) content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Template not found content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SendEmailRequest: type: object required: - from - to - subject properties: from: type: string description: | Sender email address. Must be in one of these formats: - `"Name" ` - `Name ` - `email@domain.com` maxLength: 100 example: Your Name to: oneOf: - type: string description: Single recipient email address example: recipient@example.com - type: array items: type: string maxItems: 50 description: Multiple recipient email addresses example: - recipient1@example.com - recipient2@example.com description: Recipient email addresses. Maximum 50 recipients allowed. subject: type: string description: Email subject line maxLength: 100 example: Welcome to Our Service! html: type: string description: > HTML content of the email. Required if `template_id` is not provided. - Maximum size: 40MB - Cannot be used together with `template_id` example:

Hello {{name}}!

template_id: type: string description: | ID of the email template. Required if `html` is not provided. - Cannot be used together with `html` - Must reference an existing template - Template must have valid HTML content example: welcome-template text: type: string description: Plain text version of the email. Maximum size 10MB. example: Hello {{name}}! cc: oneOf: - type: string description: Single CC recipient example: cc@example.com - type: array items: type: string maxItems: 50 description: Multiple CC recipients example: - cc1@example.com - cc2@example.com description: CC recipient addresses. Maximum 50 recipients allowed. bcc: oneOf: - type: string description: Single BCC recipient example: bcc@example.com - type: array items: type: string maxItems: 50 description: Multiple BCC recipients example: - bcc1@example.com - bcc2@example.com description: BCC recipient addresses. Maximum 50 recipients allowed. reply_to: oneOf: - type: string description: Single reply-to address example: reply@yourdomain.com - type: array items: type: string maxItems: 50 description: Multiple reply-to addresses example: - reply1@yourdomain.com - reply2@yourdomain.com description: Reply-to addresses. Maximum 50 recipients allowed. variables: type: object description: > Template variables for personalization. Maximum 100 properties allowed. Variables are referenced in templates using double curly braces: `{{variable_name}}` Note: When using templates with variables (e.g., `{{variable_name}}`): - Default values can be defined in the template - Values provided through this API field will override any template defaults - Default values will be used when: - The variable is not provided at all - The variable is explicitly set to null - When using object format and value is null or undefined Each variable can be: - A string - A number - An object with: - `value`: string, number, or null - `default`: string or number (used when value is null) maxProperties: 100 example: date: 27 November plan: value: Pro Plan default: Free Plan company: value: null default: our company title: value: null default: valued customer attachments: type: array description: > File attachments. You can attach files using either base64 encoded content or a URL path. Limits: - Maximum 10 attachments allowed - Total size must not exceed 40MB for all attachments combined - Each attachment must have: - `filename` (required) - Either `path` OR `content` (one must be provided) - `content_type` (optional, but highly recommended) - If not provided, falls back to `application/octet-stream` > **Tip**: You can upload files through the "Assets" in the template page. > These files will be served through our CDN, ensuring they are cached and optimized for delivery. Example using base64 content: ```json { "attachments": [{ "filename": "document.pdf", "content": "base64EncodedString==", "content_type": "application/pdf" }] } ``` Example using URL path: ```json { "attachments": [{ "filename": "document.pdf", "path": "https://example.com/files/document.pdf", "content_type": "application/pdf" }] } ``` Example with multiple attachments: ```json { "attachments": [ { "filename": "document.pdf", "content": "base64EncodedString==", "content_type": "application/pdf" }, { "filename": "image.jpg", "path": "https://example.com/files/image.jpg", "content_type": "image/jpeg" } ] } ``` Common errors: - `"Too many attachments: 11. Max is 10"` - `"Total attachments size exceeds maximum of 40MB"` - `"attachments[0].filename is required"` - `"attachments[0] must have either path or content"` - `"attachments[0].path must be a valid URL"` - `"attachments[0].content must be a valid base64 encoded string"` maxItems: 10 items: type: object required: - filename properties: filename: type: string description: Name of the file (required) path: type: string description: >- URL to the file content. Must be a valid URL. Required if content is not provided. format: uri content: type: string description: >- Base64 encoded file content. Must be a valid base64 string. Required if path is not provided. format: base64 content_type: type: string description: >- MIME type of the file. Highly recommended - if not provided, falls back to application/octet-stream SendEmailResponse: type: object properties: id: type: string description: Unique identifier for the sent email example: 0195c9e3-5067-741d-be87-a4f75ef93372 Error: type: object properties: message: type: string description: Error description description: | Error response with message. ### Common Errors #### 400 Bad Request Validation errors return only the error message: ```json { "message": "from field is required" } ``` Common validation messages: - `"from field is required"` - `"to field is required"` - `"subject field is required"` - `"html content size (42MB) exceeds maximum of 40MB"` - `"Too many recipients: 51. Maximum allowed is 50"` - `"Invalid email format in from field"` - `"template_id cannot be used together with html"` #### 403 Forbidden Authentication errors include both message and code: ```json { "message": "Invalid API key", "code": "invalid_api_key" } ``` ```json { "message": "Invalid authorization header", "code": "invalid_authorization_header" } ``` #### 404 Not Found ```json { "message": "Template 'welcome-email' not found" } ``` securitySchemes: bearerAuth: type: http scheme: bearer description: API key with format "Bearer {your-api-key}" ````