POST/api/v1/email/send

Send Transactional & Marketing Email

High-deliverability AWS SES email delivery engineered for D2C brands, platforms, and SaaS products. Send custom raw HTML or drag-and-drop visual templates, dynamic merge variables, PDF invoices, and track open/click events in real-time.

AWS SES Dedicated InfrastructureSPF / DKIM / DMARC 100% AlignedPrimary Inbox OptimizationMax Payload: 25 MB

Email Deliverability & Ingress Pipeline

Softymize routes every outbound email through an enterprise-grade deliverability engine with warm dedicated IP pools:

1DNS Verification

Validates your sender domain against verified DKIM public keys and SPF records to prevent spoofing.

2Suppression Filter

Automatically filters out known spam traps, unsubs, and prior hard bounces to protect your sender reputation.

3AWS SES Ingress

Dispatched with TLS 1.3 encryption directly to Gmail, Outlook, Yahoo, and enterprise MX mail exchangers.

4Engagement Tracking

Real-time webhook notifications fired for opens, clicks, delivery confirmations, and bounces.

Request Headers & Security

Header	Type	Requirement	Description
X-Softymize-API-Key	string	Required	Your SHA-256 hashed workspace production API key (starts with `sft_live_`).
Content-Type	string	Required	Must be `application/json`.
X-Idempotency-Key	string (UUID)	Optional	Unique transaction ID (e.g. `eml_ord_confirm_88219`). Guarantees zero duplicate emails during transient network retries.

Supported Email Dispatch Modes

Mode A: Visual Drag & Drop Templates

Design mobile-responsive email layouts in the Softymize Visual Email Builder. Pass template_id along with a dynamic variables object to personalize name, products, prices, and links.

Pass: template_id + variables

Mode B: Custom Raw HTML & Inline CSS

Full control for developers. Provide your raw HTML string in the html field. Softymize automatically inlines styles and creates a plain-text fallback for low-bandwidth devices.

Pass: html + optional text

Request Body Parameters

Field	Type	Description
to	string \| array (required)	Recipient email address or array of recipient emails (e.g. `"[email protected]"` or `["[email protected]", "[email protected]"]`). Supports display names like `"Rahul Sharma <[email protected]>"`.
subject	string (required)	Email subject line. Supports UTF-8 emojis and dynamic variable tags.
from_email	string (optional)	Sender email address (e.g. `[email protected]`). Must belong to a verified domain in your Softymize account. If omitted, defaults to your workspace verified sender.
from_name	string (optional)	Friendly sender display name (e.g. `"MyBrand Orders"`).
reply_to	string (optional)	Email address to route customer replies to (e.g. `[email protected]`).
template_name	string (optional)	Unique name of the template created in the Visual Builder (e.g. `"Order_Confirmation"`, `"Welcome_Series_1"`). Templates in Softymize use underscores (`_`) instead of spaces for API compatibility. When provided, `html` is optional.
template_id	integer \| string (optional)	Numeric ID (e.g. `42`) of the visual template. Alternatively, you can use `template_name`.
variables	object (optional)	Dynamic key-value pairs to inject into template placeholders like `{{first_name}}`, `{{order_id}}`, `{{total_price}}`. Variables are resolved in both the template body and the `subject` line.
html	string (optional)	Raw HTML body of the email. Required if `template_id` is not provided.
text	string (optional)	Plain-text fallback alternative for smartwatch and text-only mail clients.
cc	array of strings (optional)	Carbon copy email addresses.
bcc	array of strings (optional)	Blind carbon copy email addresses for auditing or archive purposes.
attachments	array of objects (optional)	List of attachments. Each object requires `filename`, `content` (Base64 string), and `type` (MIME type). Max total payload size: 25MB.
tags	object (optional)	Custom key-value metadata tags for analytics grouping and webhook callbacks.

Interactive Code Examples

Email API Request (CURL)curl

curl -X POST https://api.softymize.com/api/v1/email/send \
  -H "X-Softymize-API-Key: sft_live_9b8a7c6d5e4f3a2b1" \
  -H "X-Idempotency-Key: eml_ord_confirm_88219" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "from_name": "MyBrand Orders",
    "from_email": "[email protected]",
    "reply_to": "[email protected]",
    "subject": "Order Confirmed: #ORD-88219 — Thank you for your purchase!",
    "html": "<h1>Thank you for your order, Rahul!</h1><p>Your order <strong>#ORD-88219</strong> has been received and is being prepared.</p><p>Total Paid: <strong>₹2,499.00</strong></p>",
    "attachments": [
      {
        "filename": "Tax-Invoice-88219.pdf",
        "content": "JVBERi0xLjQKJcTl8uXr...",
        "type": "application/pdf"
      }
    ],
    "tags": {
      "campaign": "order_fulfillment",
      "order_id": "ORD-88219"
    }
  }'

Email Templates & Dynamic Variables Reference

Softymize enables you to design responsive, branded email layouts in the Visual Email Builder and dispatch them dynamically via API. When calling POST /api/v1/email/send, pass template_name or template_id along with a variables object to dynamically inject personalized customer and order data.

1Underscore Naming Standard

Template names in Softymize use underscores instead of spaces (e.g. Order_Confirmation). This ensures clean, URL-safe and API-safe calling without URI encoding issues.

2Dynamic Subject & Body

Variables work simultaneously in the email body AND the subject line. If subjectis omitted in the API call, the template's saved subject is automatically used.

3Universal Variable Mapping

Standard tags like {{name}} and {{order_id}} as well as any custom key in variables (e.g. {{otp}}) are automatically replaced with HTML-safe encoding.

Template Dynamic Variables Master Dictionary

Case-Insensitive • Supports Fallbacks

Placeholder Tag	Category	Description	Example Value in "variables"
{{name}} / {{full_name}}	Customer	Full name of the recipient	"Rahul Sharma"
{{first_name}}	Customer	Customer's first name	"Rahul"
{{last_name}}	Customer	Customer's last name / surname	"Sharma"
{{email}}	Customer	Recipient email address	"[email protected]"
{{phone}} / {{mobile}}	Customer	Phone number with country code	"+919876543210"
{{order_id}} / {{order_number}}	Orders	Unique order reference code	"#ORD-88219"
{{total_price}} / {{amount}}	Orders	Grand total of the order	"₹3,499.00"
{{subtotal_price}}	Orders	Items price subtotal	"₹3,199.00"
{{shipping_price}}	Orders	Delivery / Shipping charges	"₹99.00"
{{payment_method}}	Orders	Payment mode (UPI, COD, NetBanking)	"Prepaid UPI"
{{payment_status}}	Orders	Financial status (Paid, Pending)	"Paid"
{{tracking_url}}	Logistics	Direct live tracking hyperlink	"https://track.shiprocket.in/88219"
{{tracking_number}} / {{awb}}	Logistics	Courier Air Waybill (AWB) number	"SR12984712"
{{courier_name}}	Logistics	Courier partner name	"Bluedart Express"
{{product_name}}	Catalog	Featured product or item name	"Wireless Noise-Canceling Earbuds"
{{address}} / {{shipping_address}}	Address	Delivery street / house address	"Flat 402, Lotus Greens, Bandra West"
{{city}}	Address	Destination city	"Mumbai"
{{state}}	Address	Destination state or province	"Maharashtra"
{{pincode}} / {{zip}}	Address	Postal / PIN code	"400050"
{{company_name}} / {{store_name}}	Brand	Your workspace business name	"Luxe Store"
{{store_phone}}	Brand	Official support phone	"+918001234567"
{{store_website}}	Brand	Official store website URL	"https://luxestore.in"
{{unsubscribe_link}}	Compliance	One-click unsubscribe HTML link	Auto-generated anchor tag
{{any_custom_key}}	Custom	Any key you pass inside `variables` (e.g. otp, plan_name, expiry)	"Pass any string / number"

Default Fallback Syntax in Templates

You can define default fallback values inside your template text. If the API request does not provide that variable, the fallback value will render automatically:

Hello {{first_name | 'Valued Customer'}}, your exclusive offer is waiting!

Listing Saved Templates via API

GET /api/v1/email/templates

Retrieve all visual templates created in your workspace along with their IDs, names (formatted with underscores), subjects, and categories:

cURL: List Email Templatesbash

curl -X GET https://api.softymize.com/api/v1/email/templates \
  -H "X-Softymize-API-Key: sft_live_9b8a7c6d5e4f3a2b1"

Response: List Email Templates (HTTP 200)json

{
  "success": true,
  "count": 3,
  "templates": [
    {
      "id": 14,
      "name": "Order_Confirmation",
      "category": "E-Commerce",
      "subject": "Order Confirmed: #{{order_id}} — Thank you, {{first_name}}!",
      "preview_text": "Your order is confirmed and is being packed.",
      "created_at": "2026-10-15T12:00:00.000000Z",
      "updated_at": "2026-10-17T21:40:00.000000Z"
    },
    {
      "id": 18,
      "name": "Welcome_Onboarding",
      "category": "Customer Success",
      "subject": "Welcome to our family, {{first_name}}! 🚀",
      "preview_text": "Here is your 15% discount coupon.",
      "created_at": "2026-10-16T09:30:00.000000Z",
      "updated_at": "2026-10-17T18:20:00.000000Z"
    },
    {
      "id": 22,
      "name": "Abandoned_Cart_Reminder",
      "category": "Recovery",
      "subject": "Did you leave something behind, {{name}}?",
      "preview_text": "Complete your order with free delivery.",
      "created_at": "2026-10-17T11:15:00.000000Z",
      "updated_at": "2026-10-17T19:50:00.000000Z"
    }
  ]
}

Response Envelope Schemas

200 OK — Successfully Accepted by AWS SES Ingress Gateway

Success Response (HTTP 200)json

{
  "success": true,
  "email_id": "eml_7f6a5b4c3d2e1a0f",
  "channel": "email",
  "status": "queued",
  "recipient_count": 1,
  "ses_message_id": "0100018f-a931-4a2b-8a71-000000000000-000000",
  "meta": {
    "workspace_id": "ws_9a8b7c6d5e",
    "queue_latency_ms": 3,
    "timestamp": "2026-10-17T18:52:00Z"
  }
}

422 Unprocessable Entity — Missing Content or Unverified Sender Domain

Validation Error (HTTP 422)json

{
  "success": false,
  "error": {
    "code": "UNVERIFIED_SENDER_DOMAIN",
    "message": "Domain 'mybrand.com' is not verified for sending emails. Please add SPF/DKIM DNS records in Softymize Settings > Email Domains.",
    "doc_url": "https://docs.softymize.com/api-docs/email#dns-setup"
  },
  "meta": {
    "request_id": "req_8a1b2c3d4e5f6g7h",
    "timestamp": "2026-10-17T18:52:01Z"
  }
}

Error Dictionary & Troubleshooting Guide

Common status codes and error keys returned by the email service:

Error Code	HTTP Status	Cause	Resolution
UNVERIFIED_SENDER_DOMAIN	422	The domain in `from_email` has not been validated with DKIM/SPF DNS records.	Navigate to Workspace Settings > Email Domains and add the 3 CNAME DNS records provided.
SUPPRESSION_LIST_ACTIVE	422	The recipient address previously resulted in a hard bounce or spam complaint.	Remove or update the recipient email address, or request suppression list removal in workspace settings.
ATTACHMENT_SIZE_EXCEEDED	422	Total raw request payload including Base64 attachments exceeded 25MB.	Compress attachments or host large assets on CDN and include public HTTPS links inside the email body instead.
RATE_LIMIT_EXCEEDED	429	Exceeded your tier's maximum sends per second (default 100/sec).	Distribute large batch runs using Redis queues or request a quota upgrade.

Real-Time Open, Click & Bounce Webhooks

Softymize tracks every recipient action with zero latency and triggers HMAC-verified outgoing webhooks to your server:

1. email.delivered (Accepted by remote MX)

Event: email.deliveredjson

{
  "event": "email.delivered",
  "email_id": "eml_7f6a5b4c3d2e1a0f",
  "recipient": "[email protected]",
  "smtp_response": "250 2.0.0 OK 1729188720 mail-accepted",
  "timestamp": 1729188720
}

2. email.opened (1x1 pixel rendered)

Event: email.openedjson

{
  "event": "email.opened",
  "email_id": "eml_7f6a5b4c3d2e1a0f",
  "recipient": "[email protected]",
  "ip_address": "49.36.12.98",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4)",
  "timestamp": 1729188785
}

3. email.clicked (Tracked link opened)

Event: email.clickedjson

{
  "event": "email.clicked",
  "email_id": "eml_7f6a5b4c3d2e1a0f",
  "recipient": "[email protected]",
  "target_url": "https://luxestore.in/sale?coupon=FESTIVE20",
  "timestamp": 1729188810
}

4. email.bounced (Hard / Soft bounce)

Event: email.bouncedjson

{
  "event": "email.bounced",
  "email_id": "eml_7f6a5b4c3d2e1a0f",
  "recipient": "[email protected]",
  "bounce_type": "Permanent",
  "bounce_sub_type": "General",
  "diagnostic_code": "smtp; 550 5.1.1 <[email protected]>: Recipient address rejected: User unknown in virtual mailbox table",
  "timestamp": 1729188725
}

Configure Outgoing Webhooks & HMAC Verification →

Domain DNS Setup for 100% Primary Inbox Delivery (SPF, DKIM & DMARC)

To prevent your transactional and marketing emails from landing in spam or promotions tabs, configure these 3 DNS records in your domain registrar (GoDaddy, Cloudflare, Namecheap, Route53):

1. SPF (TXT Record)

Name: @
Value: v=spf1 include:amazonses.com ~all

2. DKIM (3x CNAME Records)

Generated automatically inside your Softymize dashboard with 2048-bit RSA keys.

Example: [selector]._domainkey.mybrand.com → [selector].dkim.amazonses.com

3. DMARC (TXT Record)

Name: _dmarc
Value: v=DMARC1; p=quarantine; pct=100; rua=mailto:[email protected]

← WhatsApp Business API Reference Ingest Event Payload →