> ## Documentation Index > Fetch the complete documentation index at: https://docs.sendbaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Send an email > Validates the request, stores the message, queues it and returns the id. Requires the `emails:send` scope and, for live keys, a verified sending domain, or the shared test address `onboarding@sendbaze.com`, which delivers to your organisation's own addresses only (100 emails per organisation in total). Add an `Idempotency-Key` header to make retries safe. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/emails openapi: 3.1.0 info: title: Sendbaze API version: '1.0' description: > Transactional email and SMS for Africa. Send from your own domain through Amazon SES in Cape Town. Every send returns an id immediately; delivery is reported by webhook and in the dashboard logs. contact: name: Sendbaze support email: support@sendbaze.com url: https://www.sendbaze.com servers: - url: https://api.sendbaze.com security: - bearerAuth: [] tags: - name: Emails - name: Templates - name: Domains - name: Suppressions - name: Webhooks - name: SMS - name: Usage paths: /v1/emails: post: tags: - Emails summary: Send an email description: > Validates the request, stores the message, queues it and returns the id. Requires the `emails:send` scope and, for live keys, a verified sending domain, or the shared test address `onboarding@sendbaze.com`, which delivers to your organisation's own addresses only (100 emails per organisation in total). Add an `Idempotency-Key` header to make retries safe. operationId: sendEmail parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendEmailRequest' examples: simple: summary: HTML and text value: from: Yourshop to: - thandi@example.com replyTo: help@yourshop.co.za subject: 'Your order #1042 has shipped' html: '

Tracking: CG123456789ZA

' text: 'Tracking: CG123456789ZA' tags: - order-shipped template: summary: With a template value: from: orders@yourshop.co.za to: thandi@example.com templateId: tpl_01j9x7k2r4m8q3v5n6b7c8d9e0 variables: name: Thandi order_id: 1042 eta: Friday attachment: summary: With an attachment and an inline image value: from: orders@yourshop.co.za to: thandi@example.com subject: Invoice 1042 html: >-

Your invoice is attached.

Yourshop attachments: - filename: invoice-1042.pdf contentType: application/pdf content: JVBERi0xLjQK... - filename: logo.png contentType: image/png contentId: logo content: iVBORw0KGgo... responses: '200': description: Queued content: application/json: schema: $ref: '#/components/schemas/SendEmailResponse' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/Unprocessable' '423': $ref: '#/components/responses/Locked' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Up to 255 characters. The same key and body return the same response for 24 hours. schema: type: string maxLength: 255 schemas: SendEmailRequest: type: object required: - from - to properties: from: type: string description: >- A bare address or `Name
` on a verified domain, or the shared test address `onboarding@sendbaze.com` (own addresses only). example: Yourshop to: $ref: '#/components/schemas/Recipients' cc: $ref: '#/components/schemas/Recipients' bcc: $ref: '#/components/schemas/Recipients' replyTo: type: string format: email subject: type: string maxLength: 998 description: >- Required unless `templateId` is set, in which case it overrides the template's subject. html: type: string description: >- HTML body, up to 2 MB. One of `html`, `text` or `templateId` is required. text: type: string description: Plain-text body, up to 2 MB. templateId: type: string description: >- Render a template (its current version) instead of passing html or text. variables: $ref: '#/components/schemas/TemplateVariables' attachments: type: array maxItems: 10 description: Up to 10 files, 3 MB decoded in total. items: $ref: '#/components/schemas/EmailAttachment' headers: type: object description: >- Custom headers. Standard headers such as From, To and Subject cannot be overridden. additionalProperties: type: string tags: type: array maxItems: 10 items: type: string maxLength: 64 class: allOf: - $ref: '#/components/schemas/MessageClass' default: transactional SendEmailResponse: type: object required: - id - status - mode properties: id: type: string example: em_01j9x7k2r4m8q3v5n6b7c8d9e0 status: type: string enum: - queued mode: type: string enum: - live - test description: >- `test` when sent with an sk_test_ key: validated and stored, never delivered. Recipients: description: One address or up to 50. oneOf: - type: string format: email - type: array maxItems: 50 items: type: string format: email TemplateVariables: type: object description: String, number or boolean values keyed by placeholder name. additionalProperties: oneOf: - type: string - type: number - type: boolean EmailAttachment: type: object required: - filename - content properties: filename: type: string maxLength: 255 description: Shown to the recipient. Path separators are refused. content: type: string description: The file, base64-encoded. contentType: type: string description: MIME type. Defaults to application/octet-stream. example: application/pdf contentId: type: string description: >- Set to embed the file inline and reference it from the HTML as ``. MessageClass: type: string enum: - transactional - marketing ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' ErrorBody: type: object required: - code - message properties: code: type: string description: Stable error code; see the errors reference. example: validation_error message: type: string docs: type: string format: uri fields: type: object description: Present on validation errors. Dotted path to messages. additionalProperties: type: array items: type: string limit: type: integer description: On `plan_limit`, the ceiling that was reached. upgradeUrl: type: string format: uri description: >- Where to change plan, when a bigger plan would have allowed the request. topUpUrl: type: string format: uri description: >- Where to add wallet funds, when a balance would have allowed the request. settingsUrl: type: string format: uri description: >- Where to change an organisation setting that blocked the request (SMS destinations). domainsUrl: type: string format: uri description: >- Where to add and verify a sending domain, on `sandbox_recipient_not_allowed` and `sandbox_limit_reached`. responses: PaymentRequired: description: Allowance used up, not enough credits, or plan limit reached content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: >- Insufficient scope, unverified domain, suspended organisation, or an SMS destination the organisation has not enabled (destination_not_enabled) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: domain_not_verified message: >- yourshop.co.za is not a verified sending domain of this organisation. docs: https://docs.sendbaze.com/errors#domain_not_verified PayloadTooLarge: description: Attachments over 3 MB decoded in total content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: payload_too_large message: Attachments may be at most 3 MB in total. docs: https://docs.sendbaze.com/errors#payload_too_large Unprocessable: description: >- Validation failed, a recipient is suppressed, or an SMS destination is not supported (destination_not_supported) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: validation_error message: The request has invalid fields. docs: https://docs.sendbaze.com/errors#validation_error fields: to.1: - must be a valid email address Locked: description: Sending is paused for this organisation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: >- More than 100 requests per second, or the daily warm-up cap (warmup_limit_reached); see Retry-After content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from the dashboard. `sk_live_…` sends; `sk_test_…` validates and returns ids without sending. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.