Skip to main content

​
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>"
  }'

​
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:
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

1

Verify your domain

Always verify your sending domain for better deliverability
2

Include both versions

Include both HTML and plain text versions of your email
3

Use inline CSS

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

Keep attachments small

Keep attachment sizes under 10MB for best delivery
5

Use tags

Use tags to track email campaigns and analyze performance