Sending Emails

Sending a Basic Email

The simplest way to send an email with Unosend. Works with any programming language!

curl -X POST https://api.unosend.co/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>"
  }'

await fetch('https://api.unosend.co/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer un_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'hello@yourdomain.com',
    to: ['user@example.com'],
    subject: 'Hello from Unosend!',
    html: '<h1>Hello World</h1><p>This is a test email.</p>'
  })
});

import requests

requests.post('https://api.unosend.co/emails',
  headers={'Authorization': 'Bearer un_your_api_key'},
  json={
    'from': 'hello@yourdomain.com',
    'to': ['user@example.com'],
    'subject': 'Hello from Unosend!',
    'html': '<h1>Hello World</h1><p>This is a test email.</p>'
  }
)

$ch = curl_init('https://api.unosend.co/emails');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer un_your_api_key', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'hello@yourdomain.com',
        'to' => ['user@example.com'],
        'subject' => 'Hello from Unosend!',
        'html' => '<h1>Hello World</h1><p>This is a test email.</p>'
    ])
]);
curl_exec($ch);

Response

response.json

{
  "id": "eml_xxxxxxxxxxxxxxxx",
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Hello from Unosend!",
  "status": "queued",
  "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://api.unosend.co/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://api.unosend.co/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>"
  }'

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://api.unosend.co/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://api.unosend.co/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:

Code	Description	Action
`validation_error`	Invalid request parameters	Check your request body
`domain_not_verified`	Sending domain not verified	Verify your domain first
`rate_limit_exceeded`	Too many requests	Wait and retry
`insufficient_quota`	Monthly limit reached	Upgrade 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

Verify your domain

Always verify your sending domain for better deliverability

Include both versions

Include both HTML and plain text versions of your email

Use inline CSS

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

Keep attachments small

Keep attachment sizes under 10MB for best delivery

Use tags

Use tags to track email campaigns and analyze performance

Getting Started

Guides

Resources

Sending a Basic Email

Response

Email Options

CC & BCC

Attachments

Reply-To

Sender Name Formats

Sending to Multiple Recipients

Sending Attachments

Node.js Example

Supported Content Types

Rich HTML Emails

Error Handling

Best Practices

​Sending a Basic Email

​Response

​Email Options

CC & BCC

Attachments

Reply-To

​Sender Name Formats

​Sending to Multiple Recipients

​Sending Attachments

​Node.js Example

​Supported Content Types

​Rich HTML Emails

​Error Handling

​Best Practices

Sending a Basic Email

Response

Email Options

Sender Name Formats

Sending to Multiple Recipients

Sending Attachments

Node.js Example

Supported Content Types

Rich HTML Emails

Error Handling

Best Practices