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

# Send Email

> Send a transactional email to one or more recipients.

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Body

<ParamField body="to" type="string | string[]" required>
  Recipient email address or array of up to 50 addresses.
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line. Supports `{{variable}}` template variables.
</ParamField>

<ParamField body="html" type="string">
  HTML body of the email. Supports `{{variable}}` substitution. Required if `template_id` is not provided.
</ParamField>

<ParamField body="text" type="string">
  Plain text fallback body. Recommended alongside `html`.
</ParamField>

<ParamField body="template_id" type="string">
  ID of a saved template to use. Overrides `html` / `text` if provided.
</ParamField>

<ParamField body="template_data" type="object">
  Key-value pairs for `{{variable}}` substitution in the subject, html, or template.
</ParamField>

<ParamField body="from" type="string">
  Override the sender address. Must be a verified sending domain. Defaults to your project's primary sending domain.
</ParamField>

<ParamField body="reply_to" type="string">
  Reply-to email address.
</ParamField>

<ParamField body="tags" type="object">
  Arbitrary key-value metadata attached to the log entry for filtering (e.g. `{ "type": "welcome", "user_id": "abc123" }`).
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` if all recipients were sent successfully.
</ResponseField>

<ResponseField name="sent" type="number">
  Number of successfully sent emails.
</ResponseField>

<ResponseField name="failed" type="number">
  Number of failed sends.
</ResponseField>

<ResponseField name="results" type="array">
  Per-recipient result array.

  <Expandable title="Result object">
    <ResponseField name="email" type="string">Recipient address.</ResponseField>
    <ResponseField name="status" type="string">`sent` or `failed`.</ResponseField>
    <ResponseField name="message_id" type="string">Provider message ID (when sent).</ResponseField>
    <ResponseField name="error" type="string">Error message (when failed).</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.usegately.com/api/v1/email/send \
    -H "Authorization: Bearer gately_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "user@example.com",
      "subject": "Welcome to {{project}}!",
      "html": "<h1>Hello {{name}}!</h1><p>Welcome aboard.</p>",
      "template_data": { "name": "John", "project": "Acme" },
      "tags": { "type": "welcome" }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.usegately.com/api/v1/email/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer gately_YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: 'user@example.com',
      subject: 'Welcome to {{project}}!',
      html: '<h1>Hello {{name}}!</h1><p>Welcome aboard.</p>',
      template_data: { name: 'John', project: 'Acme' },
      tags: { type: 'welcome' },
    }),
  });

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

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

  response = requests.post(
      'https://api.usegately.com/api/v1/email/send',
      headers={
          'Authorization': 'Bearer gately_YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'to': 'user@example.com',
          'subject': 'Welcome to {{project}}!',
          'html': '<h1>Hello {{name}}!</h1><p>Welcome aboard.</p>',
          'template_data': {'name': 'John', 'project': 'Acme'},
          'tags': {'type': 'welcome'},
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "sent": 1,
    "failed": 0,
    "results": [
      {
        "email": "user@example.com",
        "status": "sent",
        "message_id": "0100019fc2ed413a-69325b2f-..."
      }
    ]
  }
  ```

  ```json Partial failure (207) theme={null}
  {
    "success": false,
    "sent": 2,
    "failed": 1,
    "results": [
      { "email": "good@example.com", "status": "sent", "message_id": "..." },
      { "email": "bad@example.com", "status": "failed", "error": "SES 400: address not verified" }
    ]
  }
  ```

  ```json Unauthorized (401) theme={null}
  {
    "error": "Invalid or missing API key"
  }
  ```
</ResponseExample>

## Template variables

Use `{{variable_name}}` syntax anywhere in `subject`, `html`, or `text`, then pass values via `template_data`:

```json theme={null}
{
  "subject": "Hello {{name}}, your order #{{order_id}} is ready",
  "html": "<p>Hi {{name}}, <a href='{{link}}'>track your order</a>.</p>",
  "template_data": {
    "name": "Jane",
    "order_id": "12345",
    "link": "https://example.com/track/12345"
  }
}
```