> ## Documentation Index > Fetch the complete documentation index at: https://docs.lettr.com/llms.txt > Use this file to discover all available pages before exploring further. # Sending Introduction > Get started sending transactional and marketing emails with the Lettr API, including prerequisites, a basic send, and email options Lettr provides a powerful and flexible API for sending transactional and marketing emails. Whether you're sending password resets, order confirmations, or newsletters, the sending API handles delivery, tracking, and analytics so you can focus on building your application. ## Prerequisites Before sending your first email, make sure you have: 1. A [verified sending domain](/learn/domains/sending-domains) with DKIM and SPF records configured 2. An [API key](/learn/api-keys/introduction) with sending permissions 3. At least one of `html` or `text` content prepared for your email New to Lettr? Start with a [quickstart guide](/quickstart/nodejs/introduction) to get set up in minutes. ## Basic Email Send a simple email with minimal configuration: ```bash theme={null} curl -X POST https://app.lettr.com/api/emails \ -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "from": "you@yourdomain.com", "to": ["recipient@example.com"], "subject": "Hello World", "html": "

This is my first email!

" }' ``` ## Email Options | Parameter | Type | Required | Description | | ------------------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | string | Yes | Sender email address (must be from verified domain) | | `from_name` | string | No | Friendly sender name | | `to` | string\[] | Yes | Recipient address(es), max 50 | | `subject` | string | Conditional | Email subject line (max 998 chars). Required unless `template_slug` is provided — when omitted with a template, the template's stored subject is used (or the template name if no subject is set). | | `html` | string | No\* | HTML content | | `text` | string | No\* | Plain text content | | `amp_html` | string | No | AMP HTML content | | `cc` | string\[] | No | CC recipients | | `bcc` | string\[] | No | BCC recipients | | `reply_to` | string | No | Reply-to address | | `reply_to_name` | string | No | Reply-to display name | | `attachments` | array | No | File attachments | | `options` | object | No | Tracking and sending options | | `tag` | string | No | Tag for analytics grouping (max 64 chars) | | `metadata` | object | No | Custom metadata (available in webhooks) | | `headers` | object | No | Custom email headers (max 10, max 998 chars per value). See [Custom Headers](/api-reference/introduction#custom-headers). | | `substitution_data` | object | No | Variables for template substitution | | `template_slug` | string | No | Template slug to use for email content | | `template_version` | integer | No | Specific template version to use | | `project_id` | integer | No | Project to associate with this email | \*At least one of `html`, `text`, or `template_slug` is required. ## Response ```json theme={null} { "message": "Email queued for delivery.", "data": { "request_id": "7582751837467401763", "accepted": 1, "rejected": 0 } } ``` The `request_id` uniquely identifies this send request. Store it to track delivery status, correlate with [webhook events](/learn/webhooks/introduction), and debug issues. See [Idempotency](/learn/sending/idempotency) for patterns to prevent duplicate sends. ## Transactional vs. Marketing Emails Lettr handles both transactional and marketing emails through the same API, but the two have different characteristics and best practices. **Transactional emails** are triggered by a user action — password resets, order confirmations, shipping notifications, account alerts. They are expected by the recipient and typically have high open rates. **Marketing emails** are sent proactively — newsletters, promotions, product announcements. They require clear unsubscribe mechanisms and careful list management. Use the `transactional` option to signal the email type: ```javascript theme={null} // Transactional: password reset (transactional is true by default) await lettr.emails.send({ from: 'security@example.com', to: ['user@example.com'], subject: 'Reset your password', html: '

Click the link below to reset your password.

', options: { transactional: true } }); // Marketing: newsletter await lettr.emails.send({ from: 'updates@example.com', from_name: 'Acme Newsletter', to: ['subscriber@example.com'], subject: 'This month at Acme', html: newsletterHtml, options: { transactional: false, open_tracking: true, click_tracking: true } }); ``` Transactional emails typically have higher deliverability. Separating transactional and marketing email on different sending domains or subdomains is a common practice to protect your transactional sender reputation. See [Best Practices](/learn/sending/best-practices) for domain warm-up and reputation guidance. ### Unsubscribe Handling When you send a marketing email (`transactional: false`), Lettr automatically adds the `List-Unsubscribe` and `List-Unsubscribe-Post` headers. This enables one-click unsubscribe in email clients that support it (Gmail, Apple Mail, Outlook, etc.), which is required by major mailbox providers. For an **HTML unsubscribe link** in the email body, add the `data-msys-unsubscribe="1"` attribute to your link. The URL should point to a simple "Sorry to see you go" page — Lettr handles the unsubscribe automatically: ```html theme={null} Unsubscribe from these emails ``` For **plain text emails**, use the following format: ``` http://www.yourdomain.com[[data-msys-unsubscribe="1"]] ``` The unsubscribe URL should point to a simple "Sorry to see you go" confirmation page — it does **not** need to handle the actual unsubscription logic. Lettr processes the unsubscribe automatically and fires a `list_unsubscribe` or `link_unsubscribe` [webhook event](/learn/webhooks/introduction), which you should use to update subscription state in your application. You do not need to handle unsubscribe for transactional emails (`transactional: true`, the default). Unsubscribe headers and tracking only apply to marketing emails. ## Common Sending Patterns ### Personalized Emails with Merge Tags Use `substitution_data` to personalize content for each recipient. Lettr's [template language](/learn/templates/template-language) supports variables, conditionals, and loops: ```javascript theme={null} await lettr.emails.send({ from: 'orders@example.com', from_name: 'Acme Store', to: ['customer@example.com'], subject: 'Your order #{{order_id}} has shipped', html: `

Hi {{name}},

Your order #{{order_id}} has shipped via {{carrier}}.

Track your package: {{tracking_number}}

`, substitution_data: { name: 'Alex', order_id: '12345', carrier: 'FedEx', tracking_number: '9400111899223456789012', tracking_url: 'https://example.com/track/9400111899223456789012' } }); ``` ### Sending with Templates Instead of inline HTML, reference a template created in the Lettr dashboard or via the API: ```javascript theme={null} await lettr.emails.send({ from: 'welcome@example.com', from_name: 'Acme', to: ['newuser@example.com'], subject: 'Welcome to Acme, {{first_name}}!', template_slug: 'welcome-email', substitution_data: { first_name: 'Jordan', login_url: 'https://app.example.com/login' } }); ``` When using `template_slug`, the `subject` field is optional. If you omit it, Lettr uses the subject stored on the template (or the template name if no subject has been set). If you provide a `subject`, it overrides the template's subject — useful for A/B testing or dynamic subject lines. See [Templates](/learn/templates/introduction) for creating and managing email templates with the visual editor. ### Tracking and Metadata Attach [metadata](/learn/sending/metadata) for analytics and debugging, and control [tracking](/learn/sending/tracking) per email: ```javascript theme={null} await lettr.emails.send({ from: 'notifications@example.com', to: ['user@example.com'], subject: 'Your invoice is ready', html: '

Your invoice for January is ready. View invoice

', metadata: { invoice_id: 'inv_123', customer_id: 'cust_456', source: 'billing-service' }, options: { open_tracking: true, click_tracking: true } }); ``` Metadata is included in [webhook payloads](/learn/webhooks/introduction), allowing you to correlate delivery events with your application data. ### Sending to Multiple Recipients Send to up to 50 recipients per API call. Use `substitution_data` to personalize content with merge tags that apply to all recipients: ```javascript theme={null} await lettr.emails.send({ from: 'team@example.com', to: ['alice@example.com', 'bob@example.com', 'carol@example.com'], subject: 'Team Update', html: '

Here is the latest update for the team.

' }); ``` For larger lists, see [Batch Sending](/learn/sending/batch-sending) for patterns to send to hundreds or thousands of recipients efficiently. ## Error Handling The API returns structured errors to help you diagnose issues: ```json theme={null} { "error_code": "invalid_domain", "message": "The sending domain is not verified." } ``` Common errors include unverified domains (`invalid_domain`), unconfigured domains (`unconfigured_domain`), validation failures (`validation_error`), and template errors (`template_not_found`). Server errors (5xx) are safe to retry with exponential backoff, while client errors (4xx) should not be retried. See [Errors & Retries](/learn/sending/errors-retries) for a complete error code reference and retry patterns. ## Next Steps Once you're sending emails, there are three systems you should configure to complete your integration: * **[Webhooks](/learn/webhooks/introduction)** — Push real-time delivery, bounce, open, and click notifications to your server so you can react to events as they happen * **[Analytics](/learn/analytics/introduction)** — Aggregate dashboards for monitoring delivery rates and engagement trends over time * **[Suppressions](/learn/suppressions/introduction)** — Automatically manage bounced and unsubscribed addresses to protect your sender reputation ## Learn More HTML, plain text, and AMP email content Personalize your emails with merge tags Add files to your emails Send from Stripe, Supabase, or WordPress