> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairosafrika.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Email

> Send a single email to one or more recipients

# Send Email

This endpoint allows you to send a single email to one or more recipients.

**Endpoint:** `POST /v1/external/email/send`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.kairosafrika.com/v1/external/email/send \
    --header 'x-api-key: YOUR_API_KEY' \
    --header 'x-api-secret: YOUR_API_SECRET' \
    --header 'x-api-version: 2025-08-01' \
    --header 'Content-Type: application/json' \
    --data '{
      "from": "no-reply@example.com",
      "to": ["recipient1@example.com", "recipient2@example.com"],
      "cc": "cc@example.com",
      "bcc": "bcc@example.com",
      "subject": "Welcome to Kairos Afrika",
      "html": "<h1>Hello</h1><p>Welcome!</p>",
      "text": "Hello, welcome!",
      "replyTo": "support@example.com",
      "tags": { "campaign": "onboarding" },
      "headers": { "X-Custom": "value" }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kairosafrika.com/v1/external/email/send', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'x-api-version': '2025-08-01',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      from: 'no-reply@example.com',
      to: ['recipient1@example.com', 'recipient2@example.com'],
      cc: 'cc@example.com',
      bcc: 'bcc@example.com',
      subject: 'Welcome to Kairos Afrika',
      html: '<h1>Hello</h1><p>Welcome!</p>',
      text: 'Hello, welcome!',
      replyTo: 'support@example.com',
      tags: { campaign: 'onboarding' },
      headers: { 'X-Custom': 'value' }
    })
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.kairosafrika.com/v1/external/email/send',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'x-api-secret': 'YOUR_API_SECRET',
          'x-api-version': '2025-08-01',
          'Content-Type': 'application/json'
      },
      json={
          'from': 'no-reply@example.com',
          'to': ['recipient1@example.com', 'recipient2@example.com'],
          'cc': 'cc@example.com',
          'bcc': 'bcc@example.com',
          'subject': 'Welcome to Kairos Afrika',
          'html': '<h1>Hello</h1><p>Welcome!</p>',
          'text': 'Hello, welcome!',
          'replyTo': 'support@example.com',
          'tags': { 'campaign': 'onboarding' },
          'headers': { 'X-Custom': 'value' }
      }
  )

  result = response.json()
  print(result)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/email/send',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
      'from' => 'no-reply@example.com',
      'to' => array('recipient1@example.com', 'recipient2@example.com'),
      'cc' => 'cc@example.com',
      'bcc' => 'bcc@example.com',
      'subject' => 'Welcome to Kairos Afrika',
      'html' => '<h1>Hello</h1><p>Welcome!</p>',
      'text' => 'Hello, welcome!',
      'replyTo' => 'support@example.com',
      'tags' => array('campaign' => 'onboarding'),
      'headers' => array('X-Custom' => 'value')
    )),
    CURLOPT_HTTPHEADER => array(
      'x-api-key: YOUR_API_KEY',
      'x-api-secret: YOUR_API_SECRET',
      'x-api-version: 2025-08-01',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>
  ```
</RequestExample>

## Request Body

| Field         | Type                | Required | Description                                           |
| ------------- | ------------------- | -------- | ----------------------------------------------------- |
| `from`        | string              | Yes      | Sender email address                                  |
| `to`          | string or string\[] | Yes      | Recipient(s), max 150                                 |
| `subject`     | string              | Yes      | Email subject line                                    |
| `html`        | string              | No       | HTML content                                          |
| `text`        | string              | No       | Plain text content                                    |
| `cc`          | string or string\[] | No       | CC recipient(s), max 150                              |
| `bcc`         | string or string\[] | No       | BCC recipient(s), max 150                             |
| `replyTo`     | string              | No       | Reply-to address                                      |
| `attachments` | object\[]           | No       | File attachments                                      |
| `tags`        | object              | No       | Key-value tags (e.g. `{ "campaign": "onboarding" }`)  |
| `headers`     | object              | No       | Custom email headers (e.g. `{ "X-Custom": "value" }`) |
| `scheduledAt` | string              | No       | Schedule delivery (ISO 8601)                          |

### Attachment Object

| Field         | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `filename`    | string | Yes      | File name                          |
| `content`     | string | No       | Base64-encoded file content        |
| `path`        | string | No       | File path on server                |
| `contentType` | string | No       | MIME type (e.g. `application/pdf`) |

## Responses

### Success (200 OK)

```json theme={null}
{
  "statusCode": "200",
  "statusMessage": "Email scheduled successfully",
  "transactionId": "01J...ulid",
  "sequenceNo": "01J...ulid",
  "data": null,
  "timestamp": "2026-07-24T..."
}
```

### Error Responses

| Status Code | Description                                            |
| ----------- | ------------------------------------------------------ |
| `400`       | Validation error (invalid email, missing fields, etc.) |
| `401`       | Authentication failed (invalid API key or secret)      |
| `429`       | Rate limit exceeded (5 requests per minute)            |
| `502`       | Email service unavailable                              |


## OpenAPI

````yaml POST /v1/external/email/send
openapi: 3.0.3
info:
  title: Kairos Afrika Email API
  description: Send transactional and batch emails through Kairos Afrika via Resend.
  version: 1.0.0
  contact:
    name: Kairos Afrika Support
    email: support@kairosafrika.com
servers:
  - url: https://api.kairosafrika.com
    description: Production API
security:
  - apiKeyAuth: []
    apiSecretAuth: []
paths:
  /v1/external/email/send:
    post:
      tags:
        - Email
      summary: Send Email
      description: Send a single email to one or more recipients.
      operationId: sendEmail
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-08-01'
          description: API version header
          example: '2025-08-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '200':
          description: Email scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
        '400':
          description: Validation error
        '401':
          description: Authentication failed
        '429':
          description: Rate limit exceeded
        '502':
          description: Email service unavailable
components:
  schemas:
    SendEmailRequest:
      type: object
      properties:
        from:
          type: string
          description: Sender email address
        to:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 150
          description: Recipient(s), max 150
        subject:
          type: string
          description: Email subject line
        html:
          type: string
          description: HTML content
        text:
          type: string
          description: Plain text content
        cc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 150
          description: CC recipient(s)
        bcc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 150
          description: BCC recipient(s)
        replyTo:
          type: string
          description: Reply-to address
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        tags:
          type: object
          additionalProperties:
            type: string
          description: 'Key-value tags (e.g. { "campaign": "onboarding" })'
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom email headers
        scheduledAt:
          type: string
          description: Schedule delivery (ISO 8601)
      required:
        - from
        - to
        - subject
    SendEmailResponse:
      type: object
      properties:
        statusCode:
          type: string
          example: '200'
        statusMessage:
          type: string
          example: Email scheduled successfully
        transactionId:
          type: string
          example: 01J...ulid
        sequenceNo:
          type: string
          example: 01J...ulid
        data:
          type: object
          nullable: true
        timestamp:
          type: string
          format: date-time
    Attachment:
      type: object
      properties:
        filename:
          type: string
          description: File name
        content:
          type: string
          description: Base64-encoded file content
        path:
          type: string
          description: File path on server
        contentType:
          type: string
          description: MIME type
      required:
        - filename
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    apiSecretAuth:
      type: apiKey
      in: header
      name: x-api-secret

````