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

# Sending Emails

> Learn how to send emails with Transmit

## Basic Email

The simplest way to send an email:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await client.emails.send({
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Hello!',
    html: '<p>Welcome to our platform.</p>'
  });
  ```
</CodeGroup>

<Info>
  The examples on this page use the TypeScript SDK. A Python SDK is on the way—check back soon for updates.
</Info>

## Multiple Recipients

Send to multiple recipients using arrays:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: ['manager@example.com'],
  bcc: ['admin@example.com'],
  subject: 'Team Update',
  html: '<p>Important update for the team.</p>'
});
```

## With Attachments

Include file attachments in your emails:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Invoice #1234',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    {
      filename: 'invoice.pdf',
      content: fileBuffer, // Buffer or base64 string
      contentType: 'application/pdf'
    }
  ]
});
```

## Plain Text Alternative

Provide both HTML and plain text versions:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  text: 'Welcome! Thanks for signing up.'
});
```

<Info>
  If you only provide HTML, Transmit automatically generates a plain text version.
</Info>

## Custom Headers

Add custom email headers:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Welcome!</p>',
  headers: {
    'X-Campaign-ID': 'campaign-123',
    'X-Priority': 'high'
  }
});
```

## Reply-To Address

Set a custom reply-to address:

```typescript theme={null}
const response = await client.emails.send({
  from: 'noreply@yourdomain.com',
  replyTo: 'support@yourdomain.com',
  to: 'user@example.com',
  subject: 'Need Help?',
  html: '<p>Reply to this email for support.</p>'
});
```

## Tracking

Enable tracking for opens and clicks:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Product Update',
  html: '<p>Check out our <a href="https://example.com/new">new features</a>!</p>',
  tracking: {
    opens: true,
    clicks: true
  }
});
```

## Scheduled Sending

Schedule an email to be sent later:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Scheduled Newsletter',
  html: '<p>This newsletter was scheduled in advance.</p>',
  scheduledAt: '2025-01-15T09:00:00Z' // ISO 8601 format
});
```

## Batch Sending

Send up to 100 emails in a single API request for better efficiency:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.transmit.dev/v1/emails/batch', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify([
      {
        from: 'hello@yourdomain.com',
        to: 'user1@example.com',
        subject: 'Welcome User 1',
        html: '<p>Welcome to our platform!</p>'
      },
      {
        from: 'hello@yourdomain.com',
        to: ['user2@example.com', 'user3@example.com'],
        subject: 'Welcome Users',
        html: '<p>Welcome to our platform!</p>'
      }
    ])
  });

  const result = await response.json();
  // { data: [{ id: 'email_123' }, { id: 'email_456' }] }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.transmit.dev/v1/emails/batch \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
      {
        "from": "hello@yourdomain.com",
        "to": "user1@example.com",
        "subject": "Welcome User 1",
        "html": "<p>Welcome to our platform!</p>"
      },
      {
        "from": "hello@yourdomain.com",
        "to": "user2@example.com",
        "subject": "Welcome User 2",
        "html": "<p>Welcome to our platform!</p>"
      }
    ]'
  ```
</CodeGroup>

### Batch Limits

| Limit                    | Value |
| ------------------------ | ----- |
| Max emails per batch     | 100   |
| Max recipients per email | 50    |

### Response Format

The response contains a `data` array with a result for each email:

```json theme={null}
{
  "data": [
    { "id": "email_abc123" },
    { "id": "email_def456" },
    { "error": "All recipients suppressed" }
  ]
}
```

<Note>
  Batch requests support partial success. If some emails fail validation, others will still be processed. Check each result in the response array.
</Note>

### Billing

Each email in the batch is billed individually based on its recipient count. Credits are only consumed for successfully processed emails - failed validations don't incur charges.

### Rate Limiting

When batch requests exceed the per-second rate limit, all emails in the batch are queued for later processing. The response still returns immediately with email IDs.

## Tags for Organization

Tag emails for better organization and filtering:

```typescript theme={null}
const response = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Welcome aboard!</p>',
  tags: ['onboarding', 'welcome-series', 'day-1']
});
```

## Error Handling

Always handle errors gracefully:

```typescript theme={null}
try {
  const response = await client.emails.send({
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Hello',
    html: '<p>Hello World</p>'
  });

  console.log('Email sent:', response.id);
} catch (error) {
  if (error.code === 'invalid_email') {
    console.error('Invalid email address');
  } else if (error.code === 'rate_limit_exceeded') {
    console.error('Rate limit exceeded');
  } else {
    console.error('Error sending email:', error.message);
  }
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Verify Your Domain" icon="check-circle">
    Always verify your sending domain to improve deliverability
  </Card>

  <Card title="Use Templates" icon="file-lines">
    Create reusable templates for consistent branding
  </Card>

  <Card title="Implement Webhooks" icon="webhook">
    Track delivery status with webhook events
  </Card>

  <Card title="Monitor Metrics" icon="chart-line">
    Check analytics to optimize your email campaigns
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Email Templates" href="/guides/email-templates">
    Create and use reusable templates
  </Card>

  <Card title="Webhooks" href="/guides/webhooks">
    Track email delivery events
  </Card>
</CardGroup>