SMASHSEND Emails API Reference

1.  [        Home        ](https://smashsend.com/) / 3.  [        Docs        ](https://smashsend.com/docs) / 5.  [        API Reference        ](https://smashsend.com/docs/api) / 7.  [        Emails        ](https://smashsend.com/docs/api/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 packagenpm install @smashsend/node react-email // Create your React email componentimport { 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 SMASHSENDimport { 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 signupawait 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 laterawait 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 componentconst 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 controlawait 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 segmentsconst 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 50const 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));}```