Command Palette

Search for a command to run...

Guide

Sending Emails

Learn how to send different types of emails with Unosend, from simple messages to complex HTML emails with attachments.

Sending a Basic Email

The simplest way to send an email with Unosend:

cURL
curl -X POST https://www.unosend.co/api/v1/emails \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Hello from Unosend!",
    "html": "<h1>Hello World</h1><p>This is a test email.</p>"
  }'

Response

response.json
{
  "id": "eml_xxxxxxxxxxxxxxxx",
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Hello from Unosend!",
  "created_at": "2024-01-15T10:30:00Z"
}

Email Options

CC & BCC

Send copies to additional recipients

Attachments

Include files with your emails

Reply-To

Set a different reply address

cURL
curl -X POST https://www.unosend.co/api/v1/emails \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "John Doe <john@yourdomain.com>",
    "to": ["user@example.com"],
    "subject": "Welcome to Our Platform",
    "html": "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
    "text": "Welcome! Thanks for joining us.",
    "cc": ["manager@yourdomain.com"],
    "bcc": ["archive@yourdomain.com"],
    "reply_to": "support@yourdomain.com",
    "headers": {
      "X-Custom-Header": "custom-value"
    },
    "tags": {
      "campaign": "onboarding",
      "user_type": "new"
    }
  }'

Sender Name Formats

You can specify the sender name in different ways:

sender-formats.txt
// Email only
"from": "hello@yourdomain.com"

// Name and email
"from": "John Doe <john@yourdomain.com>"

// Company name
"from": "Acme Inc <hello@acme.com>"

// No-reply address
"from": "Acme Inc <no-reply@acme.com>"

Sending to Multiple Recipients

Send the same email to multiple recipients:

cURL
curl -X POST https://www.unosend.co/api/v1/emails \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": [
      "user1@example.com",
      "user2@example.com",
      "user3@example.com"
    ],
    "subject": "Team Update",
    "html": "<p>Hi team, here is an update...</p>"
  }'

Note: All recipients will see each other's addresses. For private sends, use BCC or send individual emails.

Sending Attachments

Attach files to your emails using base64 encoding:

cURL
curl -X POST https://www.unosend.co/api/v1/emails \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Your Monthly Report",
    "html": "<p>Please find your monthly report attached.</p>",
    "attachments": [
      {
        "filename": "report.pdf",
        "content": "base64_encoded_content_here",
        "content_type": "application/pdf"
      },
      {
        "filename": "data.csv",
        "content": "base64_encoded_content_here",
        "content_type": "text/csv"
      }
    ]
  }'

Node.js Example

attachments.js
import fs from 'fs';

// Read and encode file
const pdfBuffer = fs.readFileSync('report.pdf');
const base64Content = pdfBuffer.toString('base64');

const response = await fetch('https://www.unosend.co/api/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer un_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'billing@yourdomain.com',
    to: ['customer@example.com'],
    subject: 'Your Monthly Report',
    html: '<p>Please find your monthly report attached.</p>',
    attachments: [
      {
        filename: 'report.pdf',
        content: base64Content,
        content_type: 'application/pdf'
      }
    ]
  })
});

Supported Content Types

application/pdf
image/png
image/jpeg
text/csv
text/plain
application/zip
application/json
text/html

Rich HTML Emails

Create beautiful HTML emails with styling:

html-email.html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;">
  <div style="max-width: 600px; margin: 0 auto; padding: 20px;">
    <h1 style="color: #1a1a1a;">Welcome to Unosend!</h1>
    <p>Hi {{name}},</p>
    <p>Thanks for signing up. Here's what you can do next:</p>
    <ul>
      <li>Complete your profile</li>
      <li>Explore our features</li>
      <li>Send your first email</li>
    </ul>
    <a href="https://unosend.co/dashboard" 
       style="display: inline-block; padding: 12px 24px; 
              background: #000; color: #fff; text-decoration: none; 
              border-radius: 6px; margin-top: 16px;">
      Go to Dashboard
    </a>
    <p style="margin-top: 32px; font-size: 12px; color: #666;">
      © 2024 Your Company. All rights reserved.
    </p>
  </div>
</body>
</html>

Best Practice: Always include a plain text version (text) for email clients that don't support HTML.

Error Handling

Common error codes and how to handle them:

CodeDescriptionAction
validation_errorInvalid request parametersCheck your request body
domain_not_verifiedSending domain not verifiedVerify your domain first
rate_limit_exceededToo many requestsWait and retry
insufficient_quotaMonthly limit reachedUpgrade your plan
error-response.json
{
  "error": {
    "code": "domain_not_verified",
    "message": "The domain 'example.com' is not verified. Please verify your domain before sending."
  }
}

Best Practices

Always verify your sending domain for better deliverability

Include both HTML and plain text versions of your email

Use inline CSS for HTML emails (external stylesheets often don't work)

Keep attachment sizes under 10MB for best delivery

Use tags to track email campaigns and analyze performance