Send emails programmatically with support for HTML, text, attachments, and custom headers

Sending Emails

Send emails through the API with full support for HTML content, attachments, CC/BCC recipients, and custom headers.

Endpoint

POST /api/email/send

Authentication

Required: Bearer token in Authorization header

Authorization: Bearer YOUR_API_KEY

Request Body

Field	Type	Required	Description
`from`	string	Yes	Sender email address
`to`	string/array	Yes	Recipient email address(es)
`cc`	string/array	No	CC recipient(s)
`bcc`	string/array	No	BCC recipient(s)
`subject`	string	Yes	Email subject line
`text`	string	No	Plain text body (required if no html)
`html`	string	No	HTML body (required if no text)
`attachments`	array	No	Array of attachment objects
`replyTo`	string	No	Reply-to email address
`headers`	object	No	Custom email headers

Request Examples

Basic Text Email

curl -X POST https://api.yourdomain.com/api/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Hello World",
    "text": "This is a plain text email."
  }'

HTML Email with Multiple Recipients

curl -X POST https://api.yourdomain.com/api/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": ["user1@example.com", "user2@example.com"],
    "cc": "manager@example.com",
    "subject": "Welcome to Our Service",
    "html": "<h1>Welcome!</h1><p>Thanks for joining us.</p>",
    "replyTo": "support@yourdomain.com"
  }'

Email with Attachments

curl -X POST https://api.yourdomain.com/api/email/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Document Attached",
    "text": "Please find the document attached.",
    "attachments": [
      {
        "filename": "document.pdf",
        "content": "base64encodedcontent...",
        "contentType": "application/pdf"
      }
    ]
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "messageId": "msg_1234567890abcdef",
    "status": "queued",
    "to": ["recipient@example.com"],
    "subject": "Hello World"
  },
  "message": "Email queued for delivery"
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Invalid email address format",
    "field": "to"
  }
}

Attachment Object

Field	Type	Required	Description
`filename`	string	Yes	Name of the file
`content`	string	Yes	Base64-encoded file content
`contentType`	string	No	MIME type (auto-detected if not provided)

Rate Limits

Free tier: 100 emails/day
Pro tier: 10,000 emails/day
Enterprise: Custom limits

Webhook Events

The following events are triggered when sending emails:

email.sent - Email successfully sent
email.delivered - Email delivered to recipient
email.bounced - Email bounced
email.complaint - Spam complaint received

Best Practices

Always provide both text and HTML versions for better deliverability
Validate email addresses before sending to reduce bounces
Use reply-to for transactional emails to manage responses
Keep attachments under 25MB total per email
Implement retry logic for 5xx errors

Code Examples

JavaScript/TypeScript

const response = await fetch('https://api.yourdomain.com/api/email/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Hello',
    text: 'Hello World',
    html: '<p>Hello World</p>'
  })
});

const result = await response.json();

Python

import requests

response = requests.post(
    'https://api.yourdomain.com/api/email/send',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'from': 'sender@example.com',
        'to': 'recipient@example.com',
        'subject': 'Hello',
        'text': 'Hello World',
        'html': '<p>Hello World</p>'
    }
)

result = response.json()

Sending Emails

On this page