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

# Send Email

> Send transactional email

Send an email using raw content or a pre-built template.

## Request Body

<ParamField body="from" type="string" required>
  Sender email address. Must match a verified domain. Supports display name format: `"Name" <email@domain.com>`
</ParamField>

<ParamField body="to" type="string | string[]" required>
  Recipient email address(es). If array, all recipients see each other (single email, not batch).
</ParamField>

<ParamField body="subject" type="string">
  Email subject line (max 998 characters, no newlines). Required unless using a template.
</ParamField>

<ParamField body="html" type="string">
  HTML content of the email. Required if not using `templateId`.
</ParamField>

<ParamField body="text" type="string">
  Plain text fallback content.
</ParamField>

<ParamField body="templateId" type="string">
  Template ID to use instead of raw `html`/`text`. Subject comes from template unless overridden.
</ParamField>

<ParamField body="variables" type="object">
  Key-value pairs for template variable substitution (`{{variable}}`).
</ParamField>

<ParamField body="attachmentIds" type="string[]">
  IDs of attachments to include (from the attachments upload flow).
</ParamField>

<ParamField body="cc" type="string | string[]">
  CC recipients.
</ParamField>

<ParamField body="bcc" type="string | string[]">
  BCC recipients.
</ParamField>

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

<ParamField body="headers" type="object">
  Custom email headers to include.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Unique key to prevent duplicate sends. Valid for 24 hours, max 256 characters.
</ParamField>

## Content Options

You must provide content in one of two ways:

**Option 1: Direct Content**

```json theme={null}
{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "subject": "Welcome!",
  "html": "<h1>Welcome!</h1>",
  "text": "Welcome!"
}
```

**Option 2: Template**

```json theme={null}
{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "templateId": "welcome-template",
  "variables": {
    "name": "John",
    "plan": "Pro"
  }
}
```

## Examples

<CodeGroup>
  ```typescript JavaScript theme={null}
  import { MailBreeze } from "mailbreeze";

  const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

  // Send with direct content
  const result = await mailbreeze.emails.send({
    from: "hello@yourdomain.com",
    to: "user@example.com",
    subject: "Welcome!",
    html: "<h1>Welcome to our platform!</h1>",
    text: "Welcome to our platform!",
  });

  console.log(result.id); // "msg_xxx"

  // Send with template
  const result = await mailbreeze.emails.send({
    from: "hello@yourdomain.com",
    to: "user@example.com",
    templateId: "welcome-template",
    variables: {
      name: "John",
      plan: "Pro",
    },
  });
  ```

  ```python Python theme={null}
  from mailbreeze import MailBreeze

  client = MailBreeze(api_key="sk_live_xxx")

  # Send with direct content
  result = await client.emails.send(
      from_="hello@yourdomain.com",
      to="user@example.com",
      subject="Welcome!",
      html="<h1>Welcome to our platform!</h1>",
      text="Welcome to our platform!",
  )

  print(result.id)  # "msg_xxx"

  # Send with template
  result = await client.emails.send(
      from_="hello@yourdomain.com",
      to="user@example.com",
      template_id="welcome-template",
      variables={"name": "John", "plan": "Pro"},
  )
  ```

  ```go Go theme={null}
  client := mailbreeze.NewClient("sk_live_xxx")

  // Send with direct content
  email, err := client.Emails.Send(ctx, &mailbreeze.SendEmailParams{
      From:    "hello@yourdomain.com",
      To:      []string{"user@example.com"},
      Subject: "Welcome!",
      HTML:    "<h1>Welcome to our platform!</h1>",
      Text:    "Welcome to our platform!",
  })
  if err != nil {
      log.Fatal(err)
  }

  fmt.Println(email.ID) // "msg_xxx"

  // Send with template
  email, err := client.Emails.Send(ctx, &mailbreeze.SendEmailParams{
      From:       "hello@yourdomain.com",
      To:         []string{"user@example.com"},
      TemplateID: "welcome-template",
      Variables:  map[string]any{"name": "John", "plan": "Pro"},
  })
  ```

  ```php PHP theme={null}
  $mailbreeze = new MailBreeze('sk_live_xxx');

  // Send with direct content
  $result = $mailbreeze->emails->send([
      'from' => 'hello@yourdomain.com',
      'to' => ['user@example.com'],
      'subject' => 'Welcome!',
      'html' => '<h1>Welcome to our platform!</h1>',
      'text' => 'Welcome to our platform!',
  ]);

  echo $result['messageId']; // "abc123@mailbreeze.com"

  // Send with template
  $result = $mailbreeze->emails->send([
      'from' => 'hello@yourdomain.com',
      'to' => ['user@example.com'],
      'template_id' => 'welcome-template',
      'variables' => ['name' => 'John', 'plan' => 'Pro'],
  ]);
  ```

  ```rust Rust theme={null}
  let client = Client::new("sk_live_xxx");

  // Send with direct content
  let email = client.emails().send(SendEmailParams {
      from: "hello@yourdomain.com".to_string(),
      to: vec!["user@example.com".to_string()],
      subject: Some("Welcome!".to_string()),
      html: Some("<h1>Welcome to our platform!</h1>".to_string()),
      text: Some("Welcome to our platform!".to_string()),
      ..Default::default()
  }).await?;

  println!("{}", email.id); // "msg_xxx"

  // Send with template
  let email = client.emails().send(SendEmailParams {
      from: "hello@yourdomain.com".to_string(),
      to: vec!["user@example.com".to_string()],
      template_id: Some("welcome-template".to_string()),
      variables: Some(json!({"name": "John", "plan": "Pro"})),
      ..Default::default()
  }).await?;
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.mailbreeze.com/api/v1/emails \
    -H "Authorization: Bearer sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "hello@yourdomain.com",
      "to": ["user@example.com"],
      "subject": "Welcome!",
      "html": "<h1>Welcome to our platform!</h1>",
      "text": "Welcome to our platform!"
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique email ID.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `queued`, `sent`, `delivered`, `bounced`, or `failed`.
</ResponseField>

<ResponseField name="messageId" type="string">
  SMTP message ID.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when queued.
</ResponseField>

```json Success Response theme={null}
{
  "success": true,
  "data": {
    "messageId": "ea296955-b253-424b-9bf4-761381e8dedc"
  },
  "meta": {
    "timestamp": "2025-12-27T13:36:06.342Z",
    "requestId": "e69b115b-21e5-4051-a0bf-550c39ad7c1a",
    "path": "/api/v1/emails"
  }
}
```

### Test Mode Response

When using a test API key (`sk_test_*`), emails are simulated:

```json Sandbox Response theme={null}
{
  "success": true,
  "data": {
    "sandbox": true,
    "messageId": "sandbox_abc123xyz",
    "message": "Email simulated (test mode) - no real email was sent",
    "recipients": ["user@example.com"]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/emails"
  }
}
```

<Note>
  SDKs automatically extract the `data` field, so you access `result.messageId` directly.
</Note>

## Errors

| Code                       | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `DNS_VERIFICATION_FAILED`  | Domain DNS records not verified                |
| `DOMAIN_VALIDATION_FAILED` | Domain not active or verified                  |
| `FROM_DOMAIN_MISMATCH`     | From address domain must match verified domain |
| `TEMPLATE_NOT_FOUND`       | Template ID doesn't exist                      |
| `TEMPLATE_RENDER_ERROR`    | Template variable substitution failed          |
| `ATTACHMENT_NOT_FOUND`     | Attachment ID doesn't exist                    |
| `ATTACHMENT_TOO_LARGE`     | Attachment exceeds 10MB limit                  |
| `EMAIL_TOO_LARGE`          | Total email exceeds 10MB limit                 |
| `SPAM_SCORE_TOO_HIGH`      | Content flagged as spam                        |
| `RECIPIENT_SUPPRESSED`     | Recipient is on suppression list               |