Sending Emails

Complete guide to sending emails using the HeliosSend API.

Endpoint

POST /send

Send emails by making a POST request to the /send endpoint.

POST https://client.heliossend.com/send

Request Format

Request Body

All requests must be JSON with Content-Type: application/json

Minimal Example

{
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "subject": "Test Email",
  "html": "<p>This is a test email.</p>"
}

Note: Include your API Key in the Authorization header

Full Example

{
  "from": "sender@example.com",
  "to": ["recipient@example.com"],
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "subject": "Test Email from HeliosSend",
  "html": "<html><body><h1>Hello!</h1><p>This is a test email.</p></body></html>",
  "text": "Hello!\n\nThis is a test email.",
  "template_id": null,
  "substitutions": {},
  "metadata": {
    "source": "api",
    "campaign": "test"
  }
}

Field Reference

Request Fields

Field	Type	Required	Description
`from`	string (email)	Yes	Sender email address (domain must be verified in HeliosSend dashboard)
`to`	array[string]	Yes	List of recipient email addresses
`cc`	array[string]	No	List of CC recipient email addresses (default: [])
`bcc`	array[string]	No	List of BCC recipient email addresses (default: [])
`subject`	string	Yes	Email subject line
`html`	string	No*	HTML content of the email (*required if text not provided)
`text`	string	No*	Plain text content (fallback if HTML not provided, *required if html not provided)
`template_id`	string	No	Template ID if using a stored template
`substitutions`	object	No	Key-value pairs for template substitutions
`metadata`	object	No	Additional metadata to store with the message

Response Format

Success Response (200 OK)

{
  "message_id": "msg_abc123xyz",
  "status": "sent"
}

message_id: Unique identifier for the message. Use this to track status.

status: Current status of the message (queued, sent, failed)

Error Responses

Common Errors

401 Unauthorized - Invalid API Key

{
  "detail": "Invalid user credentials"
}

403 Forbidden - Account Not Active

{
  "detail": "Account not active"
}

500 Internal Server Error - Send Failed

{
  "detail": "Failed to send email: [error message]"
}

Important Notes

Before Sending

The from email address domain must be verified in your HeliosSend dashboard (Dashboard → Domains)
Either html or text must be provided
Include your API Key in the Authorization header
Keep your API Key secure and never expose it in client-side code
Be aware of rate limits based on your subscription tier