> ## Documentation Index > Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Send a single email > Queue a single email for delivery. Requires `email.send` permission. ## OpenAPI ````yaml https://smtp.sendmux.ai/api/v1/openapi.json post /emails/send openapi: 3.1.0 info: title: Sendmux Sending API version: 1.0.0 description: >- Send emails programmatically via the Sendmux email infrastructure. Every response carries an `X-Request-Id` header; errors include a `retryable` flag. 429 and 503 responses include `Retry-After`. Mutating endpoints accept an `Idempotency-Key` header for safe retries. servers: - url: https://smtp.sendmux.ai/api/v1 description: Production security: - BearerAuth: [] paths: /emails/send: post: tags: - Emails summary: Send a single email description: Queue a single email for delivery. Requires `email.send` permission. operationId: sendingSendEmail parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Optional client-generated key to make the request idempotent for 24 hours. Replays under the same key return the cached response; a reused key with a different body returns 409 idempotency_conflict. example: order-12345-2026-04-24 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EmailSendRequest' responses: '200': description: Email queued successfully content: application/json: schema: $ref: '#/components/schemas/SendSuccessResponse' '400': description: Malformed request (invalid JSON or syntactic parameter error) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Idempotency conflict (Idempotency-Key reused with different body, or request already in flight) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: Request body exceeds 25 MB content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation error (schema failures, accumulated in error.errors[]) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded (Retry-After header included) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable (Retry-After header included) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: EmailSendRequest: type: object properties: from: $ref: '#/components/schemas/Address' to: allOf: - $ref: '#/components/schemas/Address' - description: Primary recipient subject: type: string minLength: 1 maxLength: 998 pattern: ^[^\r\n]*$ description: Email subject line (max 998 chars, RFC 5322) example: Welcome to Sendmux html_body: type: string minLength: 1 maxLength: 26214400 description: HTML email content (max 25MB) text_body: type: string maxLength: 26214400 description: Plain text alternative (max 25MB) reply_to: allOf: - $ref: '#/components/schemas/Address' - description: Reply-To address return_path: type: string maxLength: 254 format: email description: Envelope sender for VERP support cc: type: array items: $ref: '#/components/schemas/Recipient' maxItems: 100 description: CC recipients (max 100) bcc: type: array items: $ref: '#/components/schemas/Recipient' maxItems: 100 description: BCC recipients (max 100) custom_headers: type: object additionalProperties: type: string maxLength: 500 pattern: ^[^\r\n]*$ description: Custom X-* headers to include in the email attachments: type: array items: $ref: '#/components/schemas/Attachment' maxItems: 10 description: >- File attachments (max 10). Use attachment_id refs for uploaded files. required: - from - to - subject - html_body additionalProperties: false SendSuccessResponse: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/SendSuccessData' required: - data unevaluatedProperties: false ErrorResponse: type: object properties: ok: type: boolean enum: - false error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/Meta' required: - ok - error - meta additionalProperties: false Address: type: object properties: email: type: string maxLength: 254 format: email description: Email address example: user@example.com name: type: string maxLength: 100 pattern: ^[^\r\n]*$ description: Display name example: John Smith required: - email additionalProperties: false description: Sender address Recipient: type: object properties: email: type: string maxLength: 254 format: email description: Recipient email address name: type: string maxLength: 100 pattern: ^[^\r\n]*$ description: Recipient display name required: - email additionalProperties: false Attachment: anyOf: - $ref: '#/components/schemas/InlineAttachment' - $ref: '#/components/schemas/UploadedAttachmentRef' SuccessEnvelope: type: object properties: ok: type: boolean enum: - true meta: $ref: '#/components/schemas/Meta' required: - ok - meta SendSuccessData: type: object properties: message_id: type: string pattern: ^eml_[a-z0-9]{24}$ description: Unique message identifier (eml_ prefix + 24 alphanumeric chars) example: eml_tz4a98xxat96iws9zmbrgj3a status: type: string enum: - queued description: Message queuing status required: - message_id - status additionalProperties: false ErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: validation_error message: type: string description: Human-readable error description param: type: string description: Parameter that caused the error doc_url: type: string format: uri description: Link to error documentation retryable: type: boolean description: >- True when the client may safely retry the same request. 429 and 5xx default true; 4xx default false. errors: type: array items: $ref: '#/components/schemas/ErrorIssue' description: Accumulated per-field issues (validation errors) required: - code - message - retryable additionalProperties: false Meta: type: object properties: request_id: type: string description: Unique request identifier example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx required: - request_id additionalProperties: false InlineAttachment: type: object properties: filename: type: string minLength: 1 maxLength: 255 description: Filename with allowed extension example: invoice.pdf content: type: string minLength: 1 description: Base64-encoded file content type: type: string description: MIME type override example: application/pdf encoding: type: string enum: - base64 default: base64 required: - filename - content additionalProperties: false UploadedAttachmentRef: type: object properties: attachment_id: type: string pattern: ^att_[a-z0-9]{24}$ description: >- Temporary uploaded attachment ID returned by POST /emails/attachments. example: att_tz4a98xxat96iws9zmbrgj3a required: - attachment_id additionalProperties: false ErrorIssue: type: object properties: field: type: string description: Dot-path to the failing field example: to.email code: type: string description: Issue code from the validator example: invalid_string message: type: string description: Human-readable issue message required: - field - code - message additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer description: Sendmux API key (smx_...) ````