{"id":"pg_pvzydxbxa8be","property_id":"prp_pfcr5h8cztsp","domain_id":"dom_gkgeprhezjg4wq","root_domain":"smashsend.com","locale":"en","url":"https://smashsend.com/docs/api/emails","url_hash":"198354c7ad97d2c6c3b37dba90e4c4472a28d73f1869a0b3ace9835d3415d3a3","path":"/docs/api/emails","depth":1,"canonical_url":"https://smashsend.com/docs/api/emails","canonical_page_id":null,"page_type":"docs","page_type_guess":"docs","state":"indexed","skip_reason":null,"priority":"1.4","discovered_via":"sitemap","first_seen_at":"2026-08-28T03:07:01.092Z","last_seen_at":"2026-09-27T04:10:47.779Z","http_status":200,"content_hash":"8013def6acc880b534866ebef70c2bec8f98219215ed7a4f10ba5cc9636802a0","title":"SMASHSEND Emails API Reference","description":"Complete reference for sending transactional emails via the SMASHSEND API - raw HTML, templates, and React components.","author":null,"published_at":null,"modified_at":null,"word_count":1507,"reading_time_sec":411,"lang_detected":"en","images":[],"links_out":null,"markdown_source":"readability","refresh_interval":"monthly","last_fetched_at":"2026-09-27T04:07:27.664Z","next_refresh_at":"2026-10-27T04:07:27.664Z","runs_count":2,"changes_count":0,"last_changed_at":null,"fail_count":0,"last_error":null,"created_at":"2026-08-28T03:07:01.092Z","updated_at":"2026-08-28T03:07:01.092Z","inlinks":13,"inlinks_body":0,"outlinks":40,"outlinks_external":3,"anchor_terms":[],"template_score":"0.09154929577464788732","cash":"0.418719258268548615","cash_total":"0.6330364426372252830","pagerank":"0.0162500817959562","is_orphan":false,"link_confirmed":true,"discovered_wave":0,"embedded_hash":null,"embedded_at":null,"domain_name":null,"brand_color":null,"domain_rank":null,"spam_score":null,"markdown":"1.  [\n    \n    Home\n    \n    ](https://smashsend.com/)\n\n/\n\n3.  [\n    \n    Docs\n    \n    ](https://smashsend.com/docs)\n\n/\n\n5.  [\n    \n    API Reference\n    \n    ](https://smashsend.com/docs/api)\n\n/\n\n7.  [\n    \n    Emails\n    \n    ](https://smashsend.com/docs/api/emails)\n\nThe 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.\n\n## Overview\n\nAll email endpoints require authentication via API keys with `api_user` scope. You can send individual emails or batch multiple emails in a single request.\n\n**Base URL:** `https://api.smashsend.com/v1`\n\n**Rate Limits:** Batch requests support up to 50 emails per request. Scheduling is supported up to 90 days in the future.\n\n## Authentication\n\nAll requests must include your API key in the Authorization header:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n## Verified From Addresses\n\n**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.\n\nTo add custom domains for sending, visit your domain settings in the SMASHSEND dashboard and complete the domain verification process.\n\nPOST/v1/emails\n\n## Send Single Email\n\nSend 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.\n\n## Method 1: Raw HTML Email\n\nSend emails with complete control over HTML content, styling, and structure. Perfect for custom designs and one-off emails.\n\nRequest Body (Raw Email)\n\n```\n{\n  \"from\": \"support@yourdomain.com\",\n  \"fromName\": \"Your Company Support\",\n  \"to\": \"user@example.com\",\n  \"subject\": \"Welcome to Our Platform!\",\n  \"previewText\": \"Thanks for joining us - here's what to do next\",\n  \"replyTo\": \"noreply@yourdomain.com\",\n  \"html\": \"<html><body><h1>Welcome!</h1><p>Thanks for signing up...</p></body></html>\",\n  \"text\": \"Welcome! Thanks for signing up...\",\n  \"contactProperties\": {\n    \"firstName\": \"John\",\n    \"company\": \"Acme Corp\"\n  },\n  \"settings\": {\n    \"trackClicks\": true,\n    \"trackOpens\": false\n  },\n  \"groupBy\": \"welcome_emails\",\n  \"sendAt\": \"2024-03-20T15:30:00Z\",\n  \"idempotencyKey\": \"welcome_user_12345\"\n}\n```\n\nRequest Example\n\n```\ncurl -X POST \"https://api.smashsend.com/v1/emails\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"from\": \"support@yourdomain.com\",\n    \"fromName\": \"Your Company Support\", \n    \"to\": \"user@example.com\",\n    \"subject\": \"Welcome to Our Platform!\",\n    \"previewText\": \"Thanks for joining us - here'\"'\"'s what to do next\",\n    \"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>\",\n    \"settings\": {\n      \"trackClicks\": true,\n      \"trackOpens\": false\n    },\n    \"groupBy\": \"welcome_emails\"\n  }'\n```\n\n## Method 2: Templated Email\n\nUse predefined email templates created in your SMASHSEND dashboard. Templates support variable substitution for personalization.\n\nRequest Body (Templated Email)\n\n```\n{\n  \"template\": \"welcome_email\",\n  \"to\": \"user@example.com\",\n  \"variables\": {\n    \"firstName\": \"John\",\n    \"companyName\": \"Acme Corp\",\n    \"loginUrl\": \"https://app.yourdomain.com/login\",\n    \"supportEmail\": \"support@yourdomain.com\"\n  },\n  \"settings\": {\n    \"trackClicks\": true,\n    \"trackOpens\": true\n  },\n  \"sendAt\": \"2024-03-20T15:30:00Z\",\n  \"idempotencyKey\": \"welcome_user_12345\"\n}\n```\n\nRequest Example\n\n```\ncurl -X POST \"https://api.smashsend.com/v1/emails\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"template\": \"welcome_email\",\n    \"to\": \"user@example.com\", \n    \"variables\": {\n      \"firstName\": \"John\",\n      \"companyName\": \"Acme Corp\",\n      \"loginUrl\": \"https://app.yourdomain.com/login\"\n    },\n    \"settings\": {\n      \"trackClicks\": true,\n      \"trackOpens\": true\n    }\n  }'\n```\n\n## Method 3: React Component Email\n\nGenerate emails using React components for dynamic, maintainable email templates. This approach renders React components to HTML and sends them as raw emails.\n\nJavaScript Example with React Email\n\n```\n// First, install the @smashsend/node package\nnpm install @smashsend/node react-email\n\n// Create your React email component\nimport { Html, Head, Body, Container, Heading, Text, Button } from '@react-email/components';\n\ninterface WelcomeEmailProps {\n  firstName: string;\n  companyName: string;\n  loginUrl: string;\n}\n\nexport function WelcomeEmail({ firstName, companyName, loginUrl }: WelcomeEmailProps) {\n  return (\n    <Html>\n      <Head />\n      <Body style={{ fontFamily: 'Arial, sans-serif' }}>\n        <Container>\n          <Heading>Welcome to {companyName}!</Heading>\n          <Text>Hi {firstName},</Text>\n          <Text>\n            Thanks for joining us. We're excited to have you on board!\n          </Text>\n          <Button \n            href={loginUrl}\n            style={{\n              background: '#3b82f6',\n              color: 'white',\n              padding: '12px 20px',\n              borderRadius: '6px',\n              textDecoration: 'none'\n            }}\n          >\n            Get Started\n          </Button>\n        </Container>\n      </Body>\n    </Html>\n  );\n}\n\n// Send the email using SMASHSEND\nimport { render } from '@react-email/components';\nimport { SmashSend } from '@smashsend/node';\n\nconst smashsend = new Smashsend(process.env.SMASHSEND_API_KEY);\n\nasync function sendWelcomeEmail(userEmail: string, userData: any) {\n  // Render React component to HTML\n  const emailHtml = render(WelcomeEmail({\n    firstName: userData.firstName,\n    companyName: 'Your Company',\n    loginUrl: 'https://app.yourdomain.com/login'\n  }));\n\n  // Send as raw email\n  const result = await smashsend.emails.send({\n    from: 'support@yourdomain.com',\n    fromName: 'Your Company Support',\n    to: userEmail,\n    subject: 'Welcome to Your Company!',\n    html: emailHtml,\n    settings: {\n      trackClicks: true,\n      trackOpens: true\n    },\n    groupBy: 'welcome_emails'\n  });\n\n  return result;\n}\n```\n\nResponse (All Methods)\n\n```\n{\n  \"email\": {\n    \"id\": \"trs_B7OSYsnTUVwBPOGrgYTjvSGS\",\n    \"messageId\": \"0102018e1234abcd-12345678-1234-1234-1234-123456789abc-000000@us-east-1.amazonses.com\",\n    \"status\": \"SENT\",\n    \"to\": \"user@example.com\",\n    \"type\": \"raw\", // or \"templated\"\n    \"from\": \"support@yourdomain.com\", // only for raw emails\n    \"subject\": \"Welcome to Our Platform!\", // only for raw emails\n    \"template\": \"welcome_email\", // only for templated emails\n    \"groupBy\": \"welcome_emails\" // if provided\n  }\n}\n```\n\nPOST/v1/emails/batch\n\n## Send Batch Emails\n\nSend up to 50 emails in a single request. You can mix raw and templated emails in the same batch request.\n\nRequest Body\n\n```\n{\n  \"emails\": [\n    {\n      \"from\": \"support@yourdomain.com\",\n      \"to\": \"user1@example.com\",\n      \"subject\": \"Welcome!\",\n      \"html\": \"<h1>Welcome User 1!</h1>\",\n      \"groupBy\": \"batch_welcome\"\n    },\n    {\n      \"template\": \"welcome_email\",\n      \"to\": \"user2@example.com\",\n      \"variables\": {\n        \"firstName\": \"Jane\",\n        \"companyName\": \"Acme Corp\"\n      }\n    },\n    {\n      \"from\": \"newsletter@yourdomain.com\",\n      \"to\": \"user3@example.com\", \n      \"subject\": \"Monthly Newsletter\",\n      \"html\": \"<h1>This Month's Updates</h1>\",\n      \"sendAt\": \"2024-03-20T09:00:00Z\"\n    }\n  ]\n}\n```\n\nRequest Example\n\n```\ncurl -X POST \"https://api.smashsend.com/v1/emails/batch\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"emails\": [\n      {\n        \"from\": \"support@yourdomain.com\",\n        \"to\": \"user1@example.com\",\n        \"subject\": \"Welcome User 1!\",\n        \"html\": \"<h1>Thanks for signing up!</h1><p>Welcome to our platform.</p>\"\n      },\n      {\n        \"template\": \"welcome_email\", \n        \"to\": \"user2@example.com\",\n        \"variables\": {\n          \"firstName\": \"Jane\",\n          \"companyName\": \"Acme Corp\"\n        }\n      }\n    ]\n  }'\n```\n\nResponse\n\n```\n{\n  \"emails\": {\n    \"successful\": [\n      {\n        \"id\": \"trs_B7OSYsnTUVwBPOGrgYTjvSGS\",\n        \"messageId\": \"0102018e1234abcd-12345678-1234-1234-1234-123456789abc-000000@us-east-1.amazonses.com\",\n        \"status\": \"SENT\",\n        \"to\": \"user1@example.com\",\n        \"type\": \"raw\"\n      },\n      {\n        \"id\": \"trs_C8PTZtoUVWxCQPHshZUkvTHT\",\n        \"messageId\": \"0102018e1234abcd-87654321-4321-4321-4321-987654321abc-000000@us-east-1.amazonses.com\",\n        \"status\": \"SENT\", \n        \"to\": \"user2@example.com\",\n        \"type\": \"templated\",\n        \"template\": \"welcome_email\"\n      }\n    ],\n    \"failed\": []\n  }\n}\n```\n\n## Request Parameters\n\nRaw Email Parameters\n\n`from` (required) - Sender email address or \"Name <email@domain.com>\" format\n\n`fromName` (optional) - Sender display name\n\n`to` (required) - Recipient email address\n\n`subject` (required) - Email subject line\n\n`html` (required) - HTML email content\n\n`text` (optional) - Plain text version (auto-generated from HTML if not provided)\n\n`previewText` (optional) - Email preview text shown in inbox\n\n`replyTo` (optional) - Reply-to email address\n\n`contactProperties` (optional) - Additional contact data for tracking\n\nTemplated Email Parameters\n\n`template` (required) - Name of the template created in SMASHSEND dashboard\n\n`to` (required) - Recipient email address\n\n`variables` (optional) - Key-value pairs for template variable substitution\n\nCommon Parameters (Both Types)\n\n`settings.trackClicks` (optional, default: true) - Enable click tracking\n\n`settings.trackOpens` (optional, default: true for templates, false for raw) - Enable open tracking\n\n`groupBy` (optional) - Group analytics by this identifier\n\n`sendAt` (optional) - Schedule email for future delivery (ISO 8601 format, max 90 days)\n\n`idempotencyKey` (optional) - Unique key to prevent duplicate sends\n\n## Error Handling\n\nThe API returns standard HTTP status codes. Common error responses:\n\n400 Bad Request - Invalid From Email\n\n```\n{\n  \"statusCode\": 400,\n  \"error\": \"Bad Request\",\n  \"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\",\n  \"allowedEmails\": [\"support@yourdomain.com\", \"noreply@yourdomain.com\"],\n  \"allowedDomains\": [\"yourdomain.com\"],\n  \"docsUrl\": \"https://smashsend.com/docs/api/emails#verified-from-addresses\"\n}\n```\n\n400 Bad Request - Invalid Payload\n\n```\n{\n  \"statusCode\": 400,\n  \"error\": \"Bad Request\", \n  \"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).\",\n  \"docsUrl\": \"https://smashsend.com/docs/api/emails\"\n}\n```\n\n401 Unauthorized\n\n```\n{\n  \"statusCode\": 401,\n  \"error\": \"Unauthorized\",\n  \"message\": \"Invalid API key or insufficient scope. Required scope: api_user\"\n}\n```\n\n403 Forbidden - Sending Limits\n\n```\n{\n  \"statusCode\": 403,\n  \"error\": \"Forbidden\",\n  \"message\": \"Cannot send email. Monthly sending limit reached. Upgrade your plan to send more emails.\"\n}\n```\n\n## Best Practices\n\nChoosing the Right Method\n\n• **Raw HTML:** Use for one-off emails, highly customized designs, or when you need complete control over the HTML structure\n\n• **Templates:** Best for recurring email types like welcome emails, notifications, or marketing campaigns with consistent branding\n\n• **React Components:** Ideal for complex emails with dynamic content, when you want to maintain emails in code, or need component reusability\n\nPerformance Tips\n\n• Use batch endpoints when sending multiple emails to improve throughput\n\n• Implement idempotency keys for critical emails to prevent duplicates\n\n• Use the groupBy parameter to organize analytics for different email campaigns\n\n• Schedule emails during optimal sending times using the sendAt parameter\n\nDeliverability\n\n• Always verify your sending domains before production use\n\n• Include both HTML and text versions for better deliverability\n\n• Use meaningful preview text to improve open rates\n\n• Monitor your sending reputation through the SMASHSEND dashboard\n\n## Common Use Cases\n\nUser Onboarding Flow\n\n```\n// Send welcome email immediately after signup\nawait smashsend.emails.send({\n  template: \"welcome_email\",\n  to: user.email,\n  variables: {\n    firstName: user.firstName,\n    activationUrl: generateActivationUrl(user.id)\n  },\n  groupBy: \"onboarding_flow\"\n});\n\n// Schedule follow-up email for 24 hours later\nawait smashsend.emails.send({\n  template: \"onboarding_tips\",\n  to: user.email,\n  variables: {\n    firstName: user.firstName,\n    dashboardUrl: \"https://app.yourdomain.com/dashboard\"\n  },\n  sendAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),\n  groupBy: \"onboarding_flow\"\n});\n```\n\nOrder Confirmation with Dynamic Content\n\n```\n// Generate receipt HTML from React component\nconst receiptHtml = render(OrderReceiptEmail({\n  customerName: order.customer.name,\n  orderNumber: order.id,\n  items: order.items,\n  total: order.total,\n  trackingUrl: order.trackingUrl\n}));\n\n// Send as raw email with full control\nawait smashsend.emails.send({\n  from: \"orders@yourdomain.com\",\n  fromName: \"Your Store Orders\",\n  to: order.customer.email,\n  subject: `Order Confirmation #${order.id}`,\n  html: receiptHtml,\n  settings: {\n    trackClicks: true,\n    trackOpens: true\n  },\n  groupBy: \"order_confirmations\",\n  idempotencyKey: `order_${order.id}_confirmation`\n});\n```\n\nBatch Newsletter Sending\n\n```\n// Send personalized newsletter to subscriber segments\nconst emails = subscribers.map(subscriber => ({\n  template: \"monthly_newsletter\",\n  to: subscriber.email,\n  variables: {\n    firstName: subscriber.firstName,\n    subscriberTier: subscriber.tier,\n    personalizedContent: getPersonalizedContent(subscriber)\n  },\n  groupBy: \"newsletter_march_2024\"\n}));\n\n// Send in batches of 50\nconst batches = chunkArray(emails, 50);\nfor (const batch of batches) {\n  await smashsend.emails.sendBatch({ emails: batch });\n  // Add delay between batches if needed\n  await new Promise(resolve => setTimeout(resolve, 1000));\n}\n```","storage":{"htmlKey":"stealpage/html/smashsend.com/pg_pvzydxbxa8be/run_ch_lm2cnz5yl.html.gz","markdownKey":"stealpage/md/smashsend.com/pg_pvzydxbxa8be/run_ch_lm2cnz5yl.md.gz"},"facets":null,"assets":[{"kind":"image","src_url":"https://smashsend.com/og/api_docs.jpg","r2_key":null,"alt":null,"caption":null,"width":null,"height":null,"is_hero":true,"zone":"main"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_dark.da05b6ec.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":135,"height":30,"is_hero":false,"zone":"unknown"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/zapier_icon_filled.png","r2_key":null,"alt":"Zapier","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/mailchimp_icon.png","r2_key":null,"alt":"Mailchimp","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/webhooks_icon_gradient.png","r2_key":null,"alt":"Webhooks","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/events.png","r2_key":null,"alt":"Events API","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?q=75&url=%2Favatar-profile.png&w=3840","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?url=%2Favatar-profile.png&w=3840&q=75","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_light.be8a3849.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":171,"height":38,"is_hero":false,"zone":"footer"},{"kind":"image","src_url":"https://smashsend.com/marketing/legal/gdpr_compliance.png","r2_key":null,"alt":"SOC2","caption":null,"width":null,"height":50,"is_hero":false,"zone":"footer"}],"shots":[{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_pvzydxbxa8be/run_ch_lm2cnz5yl-mobile.png","phash":"26d09cc09290a086","visual_delta":0,"captured_at":"2026-09-27T04:07:32.101Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_pvzydxbxa8be/run_ch_lm2cnz5yl-desktop.png","phash":"8662654342406061","visual_delta":0,"captured_at":"2026-09-27T04:07:31.882Z"},{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_pvzydxbxa8be/run_e_5z_p-n0f5v-mobile.png","phash":"26d09cc09290a086","visual_delta":null,"captured_at":"2026-08-28T03:07:25.344Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_pvzydxbxa8be/run_e_5z_p-n0f5v-desktop.png","phash":"8662654342406061","visual_delta":null,"captured_at":"2026-08-28T03:07:24.680Z"}],"history":[{"id":"run_ch_lm2cnz5yl","started_at":"2026-09-27T04:07:27.656Z","http_status":200,"fetcher":"direct","changed":false,"diff":{"added":0,"removed":79,"similarity":null},"word_count":1507},{"id":"run_e_5z_p-n0f5v","started_at":"2026-08-28T03:07:14.942Z","http_status":200,"fetcher":"direct","changed":false,"diff":null,"word_count":1586}],"citedBy":[]}