Sending Emails
Send transactional and marketing emails using the Smail API.
Smail lets you send emails programmatically via a simple REST API. Every email is delivered through your verified sending domain, ensuring proper authentication (SPF, DKIM).
Required fields
| Field | Description |
|---|---|
from | Sender address — must be on a verified domain |
to | Array of recipient addresses |
subject | Email subject line |
html or text | Email body — at least one is required |
When using a published template, provide template instead of html or text.
Optional fields
| Field | Description |
|---|---|
cc | Carbon copy recipients |
bcc | Blind carbon copy recipients |
reply_to | Address replies are sent to |
tags | Array of string tags for filtering in the dashboard |
attachments | Array of base64-encoded files to attach |
scheduled_at | RFC3339 timestamp for future delivery |
template | Published template reference and variables |
type | "transactional" (default) or "marketing" |
Code examples
import { SmailClient } from "@smail/smail-js";
const smail = new SmailClient({ apiKey: process.env.SMAIL_API_KEY! });
const { email } = await smail.emails.send({
from: "noreply@yourdomain.com",
to: ["user@example.com"],
subject: "Your order has shipped",
html: "<p>Your order #1234 is on its way!</p>",
text: "Your order #1234 is on its way!",
tags: ["transactional", "order-shipped"],
scheduled_at: "2026-05-14T15:30:00Z",
attachments: [
{
filename: "invoice.txt",
content_type: "text/plain",
content: "SW52b2ljZSAjMTIzNA==",
},
],
});email, err := client.Emails.Send(ctx, smail.SendEmailRequest{
From: "noreply@yourdomain.com",
To: []string{"user@example.com"},
Subject: "Your order has shipped",
HTML: "<p>Your order #1234 is on its way!</p>",
Text: "Your order #1234 is on its way!",
Tags: []string{"transactional", "order-shipped"},
ScheduledAt: "2026-05-14T15:30:00Z",
Attachments: []smail.EmailAttachment{
{
Filename: "invoice.txt",
ContentType: "text/plain",
Content: "SW52b2ljZSAjMTIzNA==",
},
},
})Email status
After sending, the returned EmailSend object includes a status field. Possible values:
| Status | Meaning |
|---|---|
queued | Email accepted and queued for delivery |
sent | Successfully handed off to the mail server |
failed | Delivery failed |
suppressed | Email was not queued because a recipient is suppressed |
Idempotency
Set the Idempotency-Key header when retrying send requests. If the first request completed successfully, Smail returns the original response for the same key and request body for 24 hours. Reusing the same key with a different request returns 409 Conflict.
Attachments
Attachments are sent as base64-encoded file bytes. Each message can include up to 10 attachments, with a maximum of 10 MB per file and 20 MB total.
Scheduled sending
Set scheduled_at to an RFC3339 timestamp in the future to delay delivery. Scheduled emails are accepted immediately and remain queued until the scheduled time.
Related
- Batch sending — send up to 1,000 emails in one API call
- Send Email reference — full endpoint documentation