Sending Emails

Learn how to send emails with Transmit

Basic Email

The simplest way to send an email:

TypeScript

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Hello!',
  html: '<p>Welcome to our platform.</p>'
});

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

Multiple Recipients

Send to multiple recipients using arrays:

const response = await client.emails.send({
  from: '[e-mail]',
  to: ['[e-mail]', '[e-mail]'],
  cc: ['[e-mail]'],
  bcc: ['[e-mail]'],
  subject: 'Team Update',
  html: '<p>Important update for the team.</p>'
});

With Attachments

Include file attachments in your emails:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  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:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Welcome',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
  text: 'Welcome! Thanks for signing up.'
});

If you only provide HTML, Transmit automatically generates a plain text version.

Custom Headers

Add custom email headers:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Welcome',
  html: '<p>Welcome!</p>',
  headers: {
    'X-Campaign-ID': 'campaign-123',
    'X-Priority': 'high'
  }
});

Reply-To Address

Set a custom reply-to address:

const response = await client.emails.send({
  from: '[e-mail]',
  replyTo: '[e-mail]',
  to: '[e-mail]',
  subject: 'Need Help?',
  html: '<p>Reply to this email for support.</p>'
});

Tracking

Enable tracking for opens and clicks:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  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:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  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:

TypeScript

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: '[e-mail]',
      to: '[e-mail]',
      subject: 'Welcome User 1',
      html: '<p>Welcome to our platform!</p>'
    },
    {
      from: '[e-mail]',
      to: ['[e-mail]', '[e-mail]'],
      subject: 'Welcome Users',
      html: '<p>Welcome to our platform!</p>'
    }
  ])
});

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

curl -X POST https://api.transmit.dev/v1/emails/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "from": "[e-mail]",
      "to": "[e-mail]",
      "subject": "Welcome User 1",
      "html": "<p>Welcome to our platform!</p>"
    },
    {
      "from": "[e-mail]",
      "to": "[e-mail]",
      "subject": "Welcome User 2",
      "html": "<p>Welcome to our platform!</p>"
    }
  ]'

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:

{
  "data": [
    { "id": "email_abc123" },
    { "id": "email_def456" },
    { "error": "All recipients suppressed" }
  ]
}

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

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:

const response = await client.emails.send({
  from: '[e-mail]',
  to: '[e-mail]',
  subject: 'Welcome',
  html: '<p>Welcome aboard!</p>',
  tags: ['onboarding', 'welcome-series', 'day-1']
});

Error Handling

Always handle errors gracefully:

try {
  const response = await client.emails.send({
    from: '[e-mail]',
    to: '[e-mail]',
    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

Verify Your Domain

Always verify your sending domain to improve deliverability

Use Templates

Create reusable templates for consistent branding

Implement Webhooks

Track delivery status with webhook events

Monitor Metrics

Check analytics to optimize your email campaigns

Next Steps

Email Templates

Create and use reusable templates

Webhooks

Track email delivery events