- Words
- 1,507
- Reading time
- 7 min
- Last crawled
- 2026-09-27
- Language
- EN
-
[
Home
/
-
[
Docs
/
-
[
API Reference
/
-
[
Emails
The SMASHSEND Emails API allows you to send transactional emails using three powerful methods: raw HTML emails for complete control, templated emails for consistency, and React component emails for dynamic, component-based email generation.
Overview
All email endpoints require authentication via API keys with api_user scope. You can send individual emails or batch multiple emails in a single request.
Base URL: https://api.smashsend.com/v1
Rate Limits: Batch requests support up to 50 emails per request. Scheduling is supported up to 90 days in the future.
Authentication
All requests must include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Verified From Addresses
Important: You can only send emails from verified email addresses or domains. If you attempt to send from an unverified address, you'll receive a 400 error with a list of allowed emails and domains.
To add custom domains for sending, visit your domain settings in the SMASHSEND dashboard and complete the domain verification process.
POST/v1/emails
Send Single Email
Send a single transactional email using either raw HTML content, a predefined template, or a React component. This endpoint supports both immediate sending and scheduled delivery.
Method 1: Raw HTML Email
Send emails with complete control over HTML content, styling, and structure. Perfect for custom designs and one-off emails.
Request Body (Raw Email)
{
"from": "support@yourdomain.com",
"fromName": "Your Company Support",
"to": "user@example.com",
"subject": "Welcome to Our Platform!",
"previewText": "Thanks for joining us - here's what to do next",
"replyTo": "noreply@yourdomain.com",
"html": "<html><body><h1>Welcome!</h1><p>Thanks for signing up...</p></body></html>",
"text": "Welcome! Thanks for signing up...",
"contactProperties": {
"firstName": "John",
"company": "Acme Corp"
},
"settings": {
"trackClicks": true,
"trackOpens": false
},
"groupBy": "welcome_emails",
"sendAt": "2024-03-20T15:30:00Z",
"idempotencyKey": "welcome_user_12345"
}
Request Example
curl -X POST "https://api.smashsend.com/v1/emails" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "support@yourdomain.com",
"fromName": "Your Company Support",
"to": "user@example.com",
"subject": "Welcome to Our Platform!",
"previewText": "Thanks for joining us - here'"'"'s what to do next",
"html": "<html><body><h1>Welcome!</h1><p>Thanks for signing up. Here are your next steps:</p><ul><li>Verify your email</li><li>Complete your profile</li><li>Explore our features</li></ul></body></html>",
"settings": {
"trackClicks": true,
"trackOpens": false
},
"groupBy": "welcome_emails"
}'
Method 2: Templated Email
Use predefined email templates created in your SMASHSEND dashboard. Templates support variable substitution for personalization.
Request Body (Templated Email)
{
"template": "welcome_email",
"to": "user@example.com",
"variables": {
"firstName": "John",
"companyName": "Acme Corp",
"loginUrl": "https://app.yourdomain.com/login",
"supportEmail": "support@yourdomain.com"
},
"settings": {
"trackClicks": true,
"trackOpens": true
},
"sendAt": "2024-03-20T15:30:00Z",
"idempotencyKey": "welcome_user_12345"
}
Request Example
curl -X POST "https://api.smashsend.com/v1/emails" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "welcome_email",
"to": "user@example.com",
"variables": {
"firstName": "John",
"companyName": "Acme Corp",
"loginUrl": "https://app.yourdomain.com/login"
},
"settings": {
"trackClicks": true,
"trackOpens": true
}
}'
Method 3: React Component Email
Generate emails using React components for dynamic, maintainable email templates. This approach renders React components to HTML and sends them as raw emails.
JavaScript Example with React Email
// First, install the @smashsend/node package
npm install @smashsend/node react-email
// Create your React email component
import { Html, Head, Body, Container, Heading, Text, Button } from '@react-email/components';
interface WelcomeEmailProps {
firstName: string;
companyName: string;
loginUrl: string;
}
export function WelcomeEmail({ firstName, companyName, loginUrl }: WelcomeEmailProps) {
return (
<Html>
<Head />
<Body style={{ fontFamily: 'Arial, sans-serif' }}>
<Container>
<Heading>Welcome to {companyName}!</Heading>
<Text>Hi {firstName},</Text>
<Text>
Thanks for joining us. We're excited to have you on board!
</Text>
<Button
href={loginUrl}
style={{
background: '#3b82f6',
color: 'white',
padding: '12px 20px',
borderRadius: '6px',
textDecoration: 'none'
}}
>
Get Started
</Button>
</Container>
</Body>
</Html>
);
}
// Send the email using SMASHSEND
import { render } from '@react-email/components';
import { SmashSend } from '@smashsend/node';
const smashsend = new Smashsend(process.env.SMASHSEND_API_KEY);
async function sendWelcomeEmail(userEmail: string, userData: any) {
// Render React component to HTML
const emailHtml = render(WelcomeEmail({
firstName: userData.firstName,
companyName: 'Your Company',
loginUrl: 'https://app.yourdomain.com/login'
}));
// Send as raw email
const result = await smashsend.emails.send({
from: 'support@yourdomain.com',
fromName: 'Your Company Support',
to: userEmail,
subject: 'Welcome to Your Company!',
html: emailHtml,
settings: {
trackClicks: true,
trackOpens: true
},
groupBy: 'welcome_emails'
});
return result;
}
Response (All Methods)
{
"email": {
"id": "trs_B7OSYsnTUVwBPOGrgYTjvSGS",
"messageId": "0102018e1234abcd-12345678-1234-1234-1234-123456789abc-000000@us-east-1.amazonses.com",
"status": "SENT",
"to": "user@example.com",
"type": "raw", // or "templated"
"from": "support@yourdomain.com", // only for raw emails
"subject": "Welcome to Our Platform!", // only for raw emails
"template": "welcome_email", // only for templated emails
"groupBy": "welcome_emails" // if provided
}
}
POST/v1/emails/batch
Send Batch Emails
Send up to 50 emails in a single request. You can mix raw and templated emails in the same batch request.
Request Body
{
"emails": [
{
"from": "support@yourdomain.com",
"to": "user1@example.com",
"subject": "Welcome!",
"html": "<h1>Welcome User 1!</h1>",
"groupBy": "batch_welcome"
},
{
"template": "welcome_email",
"to": "user2@example.com",
"variables": {
"firstName": "Jane",
"companyName": "Acme Corp"
}
},
{
"from": "newsletter@yourdomain.com",
"to": "user3@example.com",
"subject": "Monthly Newsletter",
"html": "<h1>This Month's Updates</h1>",
"sendAt": "2024-03-20T09:00:00Z"
}
]
}
Request Example
curl -X POST "https://api.smashsend.com/v1/emails/batch" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"emails": [
{
"from": "support@yourdomain.com",
"to": "user1@example.com",
"subject": "Welcome User 1!",
"html": "<h1>Thanks for signing up!</h1><p>Welcome to our platform.</p>"
},
{
"template": "welcome_email",
"to": "user2@example.com",
"variables": {
"firstName": "Jane",
"companyName": "Acme Corp"
}
}
]
}'
Response
{
"emails": {
"successful": [
{
"id": "trs_B7OSYsnTUVwBPOGrgYTjvSGS",
"messageId": "0102018e1234abcd-12345678-1234-1234-1234-123456789abc-000000@us-east-1.amazonses.com",
"status": "SENT",
"to": "user1@example.com",
"type": "raw"
},
{
"id": "trs_C8PTZtoUVWxCQPHshZUkvTHT",
"messageId": "0102018e1234abcd-87654321-4321-4321-4321-987654321abc-000000@us-east-1.amazonses.com",
"status": "SENT",
"to": "user2@example.com",
"type": "templated",
"template": "welcome_email"
}
],
"failed": []
}
}
Request Parameters
Raw Email Parameters
from (required) - Sender email address or "Name email@domain.com" format
fromName (optional) - Sender display name
to (required) - Recipient email address
subject (required) - Email subject line
html (required) - HTML email content
text (optional) - Plain text version (auto-generated from HTML if not provided)
previewText (optional) - Email preview text shown in inbox
replyTo (optional) - Reply-to email address
contactProperties (optional) - Additional contact data for tracking
Templated Email Parameters
template (required) - Name of the template created in SMASHSEND dashboard
to (required) - Recipient email address
variables (optional) - Key-value pairs for template variable substitution
Common Parameters (Both Types)
settings.trackClicks (optional, default: true) - Enable click tracking
settings.trackOpens (optional, default: true for templates, false for raw) - Enable open tracking
groupBy (optional) - Group analytics by this identifier
sendAt (optional) - Schedule email for future delivery (ISO 8601 format, max 90 days)
idempotencyKey (optional) - Unique key to prevent duplicate sends
Error Handling
The API returns standard HTTP status codes. Common error responses:
400 Bad Request - Invalid From Email
{
"statusCode": 400,
"error": "Bad Request",
"message": "The email address 'unverified@domain.com' is not verified for sending. Please use one of your verified email addresses or add a custom domain. Visit your domain settings to verify domains: https://smashsend.com/workspace-slug/settings/domains",
"allowedEmails": ["support@yourdomain.com", "noreply@yourdomain.com"],
"allowedDomains": ["yourdomain.com"],
"docsUrl": "https://smashsend.com/docs/api/emails#verified-from-addresses"
}
400 Bad Request - Invalid Payload
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid email payload: Must match either the Raw Email schema (required fields: from, to, subject, html) or the Templated Email schema (required fields: template, to, variables).",
"docsUrl": "https://smashsend.com/docs/api/emails"
}
401 Unauthorized
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid API key or insufficient scope. Required scope: api_user"
}
403 Forbidden - Sending Limits
{
"statusCode": 403,
"error": "Forbidden",
"message": "Cannot send email. Monthly sending limit reached. Upgrade your plan to send more emails."
}
Best Practices
Choosing the Right Method
• Raw HTML: Use for one-off emails, highly customized designs, or when you need complete control over the HTML structure
• Templates: Best for recurring email types like welcome emails, notifications, or marketing campaigns with consistent branding
• React Components: Ideal for complex emails with dynamic content, when you want to maintain emails in code, or need component reusability
Performance Tips
• Use batch endpoints when sending multiple emails to improve throughput
• Implement idempotency keys for critical emails to prevent duplicates
• Use the groupBy parameter to organize analytics for different email campaigns
• Schedule emails during optimal sending times using the sendAt parameter
Deliverability
• Always verify your sending domains before production use
• Include both HTML and text versions for better deliverability
• Use meaningful preview text to improve open rates
• Monitor your sending reputation through the SMASHSEND dashboard
Common Use Cases
User Onboarding Flow
// Send welcome email immediately after signup
await smashsend.emails.send({
template: "welcome_email",
to: user.email,
variables: {
firstName: user.firstName,
activationUrl: generateActivationUrl(user.id)
},
groupBy: "onboarding_flow"
});
// Schedule follow-up email for 24 hours later
await smashsend.emails.send({
template: "onboarding_tips",
to: user.email,
variables: {
firstName: user.firstName,
dashboardUrl: "https://app.yourdomain.com/dashboard"
},
sendAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
groupBy: "onboarding_flow"
});
Order Confirmation with Dynamic Content
// Generate receipt HTML from React component
const receiptHtml = render(OrderReceiptEmail({
customerName: order.customer.name,
orderNumber: order.id,
items: order.items,
total: order.total,
trackingUrl: order.trackingUrl
}));
// Send as raw email with full control
await smashsend.emails.send({
from: "orders@yourdomain.com",
fromName: "Your Store Orders",
to: order.customer.email,
subject: `Order Confirmation #${order.id}`,
html: receiptHtml,
settings: {
trackClicks: true,
trackOpens: true
},
groupBy: "order_confirmations",
idempotencyKey: `order_${order.id}_confirmation`
});
Batch Newsletter Sending
// Send personalized newsletter to subscriber segments
const emails = subscribers.map(subscriber => ({
template: "monthly_newsletter",
to: subscriber.email,
variables: {
firstName: subscriber.firstName,
subscriberTier: subscriber.tier,
personalizedContent: getPersonalizedContent(subscriber)
},
groupBy: "newsletter_march_2024"
}));
// Send in batches of 50
const batches = chunkArray(emails, 50);
for (const batch of batches) {
await smashsend.emails.sendBatch({ emails: batch });
// Add delay between batches if needed
await new Promise(resolve => setTimeout(resolve, 1000));
}
