Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.
Sends an email to one or more recipients. Supports HTML, plain text, AMP content, templates, merge tags, attachments, and tracking options.Open and click tracking are enabled by default. Set options.open_tracking or options.click_tracking to false in the request body to disable either. The X-Lettr-Track-* control headers are SMTP-only; see Tracking for examples.Available to sandbox API keys: all recipients are redirected to the key owner’s inbox and the sender domain is replaced with the pre-verified sandbox domain.
Authorizations
Authorization
string
header
required
API key for authentication
Headers
Idempotency-Key
string
A unique key for one logical send. Reuse it with the same payload and API key when retrying. SparkPost retains the key for 24 hours. If using a template, keep the resolved template content unchanged across retries.
Required string length: 1 - 255
Pattern: ^[A-Za-z0-9._-]{1,255}$
Body
application/json
Email sending request. Required:from, to, and at least one of html, text, or template_slug. The subject is required unless template_slug is provided — when using a template, the subject defaults to the template's subject (or template name as fallback), but can be overridden. When using template_slug, if project_id is not provided, the team's default project will be used.
from
string<email>
required
Sender email address
Maximum string length: 255
Example:
"sender@example.com"
to
string<email>[]
required
Recipient email addresses
Required array length: 1 - 50 elements
Maximum string length: 255
Example:
["recipient@example.com"]
from_name
string | null
Sender display name
Maximum string length: 255
Example:
"Sender Name"
subject
string | null
Email subject line. Required when not using a template. When using template_slug, defaults to the template's subject (or template name as fallback). If provided alongside a template, overrides the template subject.
Maximum string length: 998
Example:
"Welcome to Lettr"
cc
string<email>[]
Carbon copy recipient email addresses
Maximum string length: 255
Example:
["cc@example.com"]
bcc
string<email>[]
Blind carbon copy recipient email addresses
Maximum string length: 255
Example:
["bcc@example.com"]
reply_to
string<email> | null
Reply-To email address
Maximum string length: 255
Example:
"reply@example.com"
reply_to_name
string | null
Reply-To display name
Maximum string length: 255
Example:
"Reply Name"
html
string | null
HTML content of the email. At least one of html or text is required, but providing both is recommended for best compatibility across email clients.
Example:
"<h1>Hello</h1><p>Welcome!</p>"
text
string | null
Plain text content of the email. At least one of html or text is required, but providing both is recommended for best compatibility across email clients.
Example:
"Hello\n\nWelcome!"
amp_html
string | null
AMP HTML content for supported email clients
project_id
integer | null
Project ID containing the template. If not provided when using template_slug, the team's default project will be used.
Example:
123
template_slug
string | null
Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.
Maximum string length: 255
Example:
"welcome-email"
template_version
integer | null
Specific template version to use. If not provided, the active version will be used.
Required range: x >= 1
Example:
1
tag
string
Tag for tracking and analytics. Automatically set from template_slug if not provided.
Maximum string length: 64
Example:
"welcome-series-2024"
metadata
object
Custom metadata attached to the email for tracking purposes
Show child attributes
Example:
{ "user_id": "12345", "campaign": "onboarding" }
headers
object
Custom email headers. Up to 10 headers allowed. Standard envelope headers (From, To, Subject, etc.), SparkPost internal headers (X-MSYS-API), and List-Unsubscribe and List-Unsubscribe-Post headers are managed by the system and cannot be set manually.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/schema.json","name":"Lettr","colors":{"primary":"#EC104B","light":"#F04070","dark":"#D00E43"},"logo":{"light":"https://mintcdn.com/lettr/w6cQMnBCGTvjJ4__/logo/light.svg?fit=max\u0026auto=format\u0026n=w6cQMnBCGTvjJ4__\u0026q=85\u0026s=2cad5a94a80e61999cf9feaeac06e9c6","dark":"https://mintcdn.com/lettr/w6cQMnBCGTvjJ4__/logo/dark.svg?fit=max\u0026auto=format\u0026n=w6cQMnBCGTvjJ4__\u0026q=85\u0026s=2d94948c6f2c26d1375758ec890ccd4b","href":"/introduction"},"favicon":"https://mintcdn.com/lettr/MeT4pWpyRN-RhvgL/favicon.svg?fit=max\u0026auto=format\u0026n=MeT4pWpyRN-RhvgL\u0026q=85\u0026s=800c7fba1be1e2324447ed3b67ef0a48","api":{},"appearance":{"default":"dark"},"navbar":{"links":[{"href":"https://status.lettr.com/","label":"Status"},{"href":"https://lettr.com/support","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.lettr.com"}},"footer":{"socials":{"x":"https://x.com/lettr_com","linkedin":"https://www.linkedin.com/company/lettr-com","github":"https://github.com/lettr-com"}},"fonts":{"heading":{"family":"Manrope","weight":400},"body":{"family":"Manrope"}},"integrations":{"ga4":{"measurementId":"G-GMH8JTRY9Q"},"posthog":{"apiKey":"phc_67BYz5Uv0uoiydQyaN3OyeK9OPx6LjmFDFvF0mNaTy9","apiHost":"https://eu.i.posthog.com","sessionRecording":true}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"lettr","hasAudioNarration":false,"actualSubdomain":"lettr","customDomains":["docs.lettr.com"],"gitSource":{"type":"github","owner":"lettr-com","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"feedback":{"edits":true,"thumbs":true,"issues":true},"entitlements":{},"buildId":"6afdbd922d5b5666c136f0d2","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"Documentation","count":186},{"language":"default","tag":"Learn","count":110},{"language":"default","tag":"Knowledge Base","count":87},{"language":"default","tag":"API Reference","count":72},{"language":"default","tag":"Quickstart","count":68},{"language":"default","tag":"DNS Guides","count":19},{"language":"default","tag":"Templates","count":18},{"language":"default","tag":"Domains","count":16},{"language":"default","tag":"Email Fundamentals","count":15},{"language":"default","tag":"Troubleshooting","count":15}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":":root{--rounded: 0px;--rounded-sm: 0px;--rounded-md: 0px;--rounded-lg: 0px;--rounded-xl: 0px;--rounded-2xl: 0px;--rounded-3xl: 0px;--rounded-search: 0px;--c15t-radius-sm: 0px;--c15t-radius-md: 0px;--c15t-radius-lg: 0px;--cdt-radius: 0px;--accordion-radius: 0px;--button-border-radius: 0px;--consent-banner-border-radius: 0px;--consent-dialog-card-radius: 0px;--consent-widget-radius: 0px;--consent-widget-accordion-radius: 0px;--frame-placeholder-border-radius: 0px;--scrollbar-track-radius: 0px;--scrollbar-thumb-radius: 0px;--scrollbar-corner-radius: 0px}*,*::before,*::after,::backdrop,::file-selector-button{border-radius:0!important}[class~=\"rounded-full\"],[class~=\"rounded-full!\"]{border-radius:9999px!important}.prose :where(ul>li)::before,.prose-sm :where(ul>li)::before,.latex-style ul>li::before{border-radius:50%!important}.sdk-list{--sdk-fg: rgb(24 14 19);--sdk-muted: rgb(24 14 19 / 0.55);--sdk-line: rgb(60 20 35 / 0.1);--sdk-hover: rgb(236 16 75 / 0.035);--sdk-code-bg: rgb(60 20 35 / 0.035);--sdk-code-line: rgb(60 20 35 / 0.12);--sdk-accent: #d00e43;--sdk-ease: cubic-bezier(0.22, 1, 0.36, 1);margin:1.25rem 0 2.5rem;border-top:1px solid var(--sdk-line)}.dark .sdk-list{--sdk-fg: rgb(250 242 245);--sdk-muted: rgb(250 242 245 / 0.5);--sdk-line: rgb(255 225 235 / 0.09);--sdk-hover: rgb(240 64 112 / 0.05);--sdk-code-bg: rgb(255 225 235 / 0.035);--sdk-code-line: rgb(255 225 235 / 0.1);--sdk-accent: #f04070}.sdk-row{position:relative;display:grid;grid-template-columns:1.25rem 8.75rem minmax(0, 1fr) 1rem;align-items:center;column-gap:1rem;padding:0.875rem 0.75rem;border-bottom:1px solid var(--sdk-line);transition:background-color 180ms var(--sdk-ease)}.sdk-row:hover{background-color:var(--sdk-hover)}.sdk-row:has(.sdk-row__name:focus-visible){outline:2px solid var(--sdk-accent);outline-offset:-2px}.sdk-row__logo{display:flex;align-items:center;justify-content:center;color:var(--sdk-muted);transition:color 180ms var(--sdk-ease)}.sdk-row__logo svg,.sdk-row__logo span{background-color:currentColor!important}.sdk-row:hover .sdk-row__logo{color:var(--sdk-fg)}.sdk-row__name{position:static!important;z-index:auto!important;font-size:0.9375rem;font-weight:600;letter-spacing:-0.005em;color:var(--sdk-fg);text-decoration:none;white-space:nowrap}.sdk-row__name:focus-visible{outline:none}.sdk-row__name::after{content:\"\";position:absolute;inset:0}.sdk-row__install{position:relative;z-index:1;justify-self:start;display:inline-flex;align-items:center;gap:0.625rem;max-width:100%;min-width:0;padding:0.3125rem 0.5rem 0.3125rem 0.625rem;border:1px solid var(--sdk-code-line);background:var(--sdk-code-bg);color:var(--sdk-fg);cursor:pointer;transition:border-color 180ms var(--sdk-ease)}.sdk-row__install:hover{border-color:var(--sdk-accent)}.sdk-row__install:focus-visible{outline:2px solid var(--sdk-accent);outline-offset:2px}.sdk-row__install code{padding:0!important;border:0!important;background:none!important;color:inherit!important;overflow:hidden;font-size:0.8125rem;line-height:1.4;text-overflow:ellipsis;white-space:nowrap}.sdk-row__copy{display:flex;flex-shrink:0;color:var(--sdk-muted);transition:color 180ms var(--sdk-ease)}.sdk-row__install:hover .sdk-row__copy,.sdk-row__copy[data-copied=\"true\"]{color:var(--sdk-accent)}.sdk-row__arrow{color:var(--sdk-muted);transition:transform 220ms var(--sdk-ease),\n color 180ms var(--sdk-ease)}.sdk-row:hover .sdk-row__arrow{color:var(--sdk-accent);transform:translate(2px, -2px)}.sdk-row__sr{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}.sdk-list--inline{margin:0 0 1.25rem}:has(+.sdk-list--inline){margin-bottom:0.625rem!important}@media (max-width: 640px){.sdk-row{grid-template-columns:1.25rem minmax(0, 1fr) 1rem;row-gap:0.625rem;padding:0.875rem 0.5rem}.sdk-row__install{grid-row:2;grid-column:2 / 4;justify-self:stretch;justify-content:space-between;min-height:2.75rem;padding-block:0.5rem;text-align:left}.sdk-row__install code{white-space:normal;overflow-wrap:anywhere}}@media (prefers-reduced-motion: reduce){.sdk-row,.sdk-row__logo,.sdk-row__install,.sdk-row__copy,.sdk-row__arrow{transition:none}.sdk-row:hover .sdk-row__arrow{transform:none}}.whitespace-pre-wrap>pre.shiki,.whitespace-pre-wrap>pre.shiki code{white-space:pre-wrap!important;overflow-wrap:anywhere}[data-component-part=\"card-icon\"]:has(>img[src*=\"/images/integrations/\"]){display:flex;align-items:center;width:auto}[data-component-part=\"card-icon\"]>img[src*=\"/images/integrations/\"]{width:auto;height:1.25rem;object-position:-9999px 0;background-color:rgb(var(--primary));mask:var(--partner-logo) center / contain no-repeat}.dark [data-component-part=\"card-icon\"]>img[src*=\"/images/integrations/\"]{background-color:rgb(var(--primary-light))}[data-component-part=\"card-icon\"]>img[src*=\"/integrations/apiant.svg\"]{--partner-logo: url(\"/images/integrations/apiant.svg\")}[data-component-part=\"card-icon\"]>img[src*=\"/integrations/elaichi.svg\"]{--partner-logo: url(\"/images/integrations/elaichi.svg\")}[data-component-part=\"card-icon\"]>img[src*=\"/integrations/flowrunner.svg\"]{--partner-logo: url(\"/images/integrations/flowrunner.svg\")}[data-component-part=\"card-icon\"]>img[src*=\"/integrations/truto.svg\"]{--partner-logo: url(\"/images/integrations/truto.svg\")}[data-component-part=\"card-icon\"]>img[src*=\"/integrations/unified.svg\"]{--partner-logo: url(\"/images/integrations/unified.svg\")}"}],"page":{"pagePath":"api-reference/emails/send-email","slug":"/api-reference/emails/send-email","pageMetadata":{"title":"Send Email","openapi":"POST /emails","description":"Send a transactional email with optional attachments, tracking, and personalization. At least one of `html` or `text` content must be provided. Supply `Idempotency-Key` for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.","href":"/api-reference/emails/send-email"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Send a transactional email with optional attachments, tracking, and personalization. At least one of \", _jsx(_components.code, {\n children: \"html\"\n }), \" or \", _jsx(_components.code, {\n children: \"text\"\n }), \" content must be provided. Supply \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,..._provideComponents(),...props.components};return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Sends an email to one or more recipients. Supports HTML, plain text, AMP content, templates, merge tags, attachments, and tracking options.`}),`\n`,_jsxs(_components.p,{children:[`Open and click tracking are enabled by default. Set `,_jsx(_components.code,{children:`options.open_tracking`}),` or `,_jsx(_components.code,{children:`options.click_tracking`}),` to `,_jsx(_components.code,{children:`false`}),` in the request body to disable either. The `,_jsx(_components.code,{children:`X-Lettr-Track-*`}),` control headers are SMTP-only; see `,_jsx(_components.a,{href:`/learn/sending/tracking`,children:`Tracking`}),` for examples.`]}),`\n`,_jsxs(_components.p,{children:[`Available to `,_jsx(_components.a,{href:`/learn/api-keys/sandbox`,children:`sandbox API keys`}),`: all recipients are redirected to the key owner’s inbox and the sender domain is replaced with the pre-verified sandbox domain.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Send Email","openapi":"POST /emails","description":"Send a transactional email with optional attachments, tracking, and personalization. At least one of `html` or `text` content must be provided. Supply `Idempotency-Key` for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.","href":"/api-reference/emails/send-email"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"sendEmail","summary":"Send Email","description":"Send a transactional email with optional attachments, tracking, and personalization. At least one of `html` or `text` content must be provided. Supply `Idempotency-Key` for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.","parameters":["c33a5fde-3674-4d51-ba3b-355b825ed7ed"],"tags":["Emails"],"security":["42617010-5738-4e0f-95ed-272f074cfd32"],"requestBody":"ae70bb50-a663-491c-94f2-bbd844b810b5","responses":{"200":"4fc8a725-d1c7-41f9-96ed-b32c3c83d19f","400":"983a6290-bb80-4487-83d0-55bc36adad25","401":"c5093cb4-680d-4aed-aeb4-529dd7a584ff","404":"8bf20a6e-df04-4a40-a8c7-95659635b409","409":"679ca8bb-ad4e-4a9f-b563-fbbcd024d26f","422":"9622739b-8c69-482a-a686-54a3c4931479","429":"d4075786-dcfe-4aaa-9fcf-cc7a90293437","500":"19fae837-9f0b-4310-9c0f-b00b58268e7c","502":"3eb42fc6-f3a2-4095-b988-735e0556c8ba","503":"4ff669d0-12ed-49b1-9ac2-413ada730cf6"},"method":"post","type":"path","servers":["3a9a6297-5f46-49ab-955a-fb22c45ca41c"],"path":"/emails","baseUrlOptions":["https://app.lettr.com/api"],"title":"Send Email","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"c33a5fde-3674-4d51-ba3b-355b825ed7ed":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key for one logical send. Reuse it with the same payload and API key when retrying. SparkPost retains the key for 24 hours. If using a template, keep the resolved template content unchanged across retries.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9._-]{1,255}$","isRequired":false,"description":"A unique key for one logical send. Reuse it with the same payload and API key when retrying. SparkPost retains the key for 24 hours. If using a template, keep the resolved template content unchanged across retries.","uniqueKey":"","typeLabel":"string"},"example":"order-confirmation-12345"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Email sending request. **Required:** `from`, `to`, and at least one of `html`, `text`, or `template_slug`. The `subject` is required unless `template_slug` is provided — when using a template, the subject defaults to the template's subject (or template name as fallback), but can be overridden. When using `template_slug`, if `project_id` is not provided, the team's default project will be used.","required":["from","to"],"properties":{"from":{"type":"string","format":"email","maxLength":255,"description":"Sender email address","example":"sender@example.com","isRequired":true,"uniqueKey":"from","typeLabel":"string\u003cemail>"},"to":{"type":"array","description":"Recipient email addresses","minItems":1,"maxItems":50,"items":{"type":"string","format":"email","maxLength":255,"uniqueKey":"to.items.[INDEX]","typeLabel":"string\u003cemail>"},"example":["recipient@example.com"],"isRequired":true,"uniqueKey":"to","typeLabel":"string\u003cemail>[]"},"from_name":{"oneOf":[{"type":"string","maxLength":255,"description":"Sender display name","example":"Sender Name","uniqueKey":"from_name.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":255,"description":"Sender display name","example":"Sender Name","uniqueKey":"from_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"from_name","typeLabel":"string | null"},"subject":{"oneOf":[{"type":"string","maxLength":998,"description":"Email subject line. Required when not using a template. When using `template_slug`, defaults to the template's subject (or template name as fallback). If provided alongside a template, overrides the template subject.","example":"Welcome to Lettr","uniqueKey":"subject.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":998,"description":"Email subject line. Required when not using a template. When using `template_slug`, defaults to the template's subject (or template name as fallback). If provided alongside a template, overrides the template subject.","example":"Welcome to Lettr","uniqueKey":"subject.oneOf.1","typeLabel":"null"}],"uniqueKey":"subject","typeLabel":"string | null"},"cc":{"type":"array","description":"Carbon copy recipient email addresses","items":{"type":"string","format":"email","maxLength":255,"uniqueKey":"cc.items.[INDEX]","typeLabel":"string\u003cemail>"},"example":["cc@example.com"],"uniqueKey":"cc","typeLabel":"string\u003cemail>[]"},"bcc":{"type":"array","description":"Blind carbon copy recipient email addresses","items":{"type":"string","format":"email","maxLength":255,"uniqueKey":"bcc.items.[INDEX]","typeLabel":"string\u003cemail>"},"example":["bcc@example.com"],"uniqueKey":"bcc","typeLabel":"string\u003cemail>[]"},"reply_to":{"oneOf":[{"type":"string","format":"email","maxLength":255,"description":"Reply-To email address","example":"reply@example.com","uniqueKey":"reply_to.oneOf.0","typeLabel":"string\u003cemail>"},{"type":"null","format":"email","maxLength":255,"description":"Reply-To email address","example":"reply@example.com","uniqueKey":"reply_to.oneOf.1","typeLabel":"null"}],"uniqueKey":"reply_to","typeLabel":"string\u003cemail> | null"},"reply_to_name":{"oneOf":[{"type":"string","maxLength":255,"description":"Reply-To display name","example":"Reply Name","uniqueKey":"reply_to_name.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":255,"description":"Reply-To display name","example":"Reply Name","uniqueKey":"reply_to_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"reply_to_name","typeLabel":"string | null"},"html":{"oneOf":[{"type":"string","description":"HTML content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.","example":"\u003ch1>Hello\u003c/h1>\u003cp>Welcome!\u003c/p>","uniqueKey":"html.oneOf.0","typeLabel":"string"},{"type":"null","description":"HTML content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.","example":"\u003ch1>Hello\u003c/h1>\u003cp>Welcome!\u003c/p>","uniqueKey":"html.oneOf.1","typeLabel":"null"}],"uniqueKey":"html","typeLabel":"string | null"},"text":{"oneOf":[{"type":"string","description":"Plain text content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.","example":"Hello\n\nWelcome!","uniqueKey":"text.oneOf.0","typeLabel":"string"},{"type":"null","description":"Plain text content of the email. At least one of `html` or `text` is required, but providing both is recommended for best compatibility across email clients.","example":"Hello\n\nWelcome!","uniqueKey":"text.oneOf.1","typeLabel":"null"}],"uniqueKey":"text","typeLabel":"string | null"},"amp_html":{"oneOf":[{"type":"string","description":"AMP HTML content for supported email clients","uniqueKey":"amp_html.oneOf.0","typeLabel":"string"},{"type":"null","description":"AMP HTML content for supported email clients","uniqueKey":"amp_html.oneOf.1","typeLabel":"null"}],"uniqueKey":"amp_html","typeLabel":"string | null"},"project_id":{"oneOf":[{"type":"integer","description":"Project ID containing the template. If not provided when using template_slug, the team's default project will be used.","example":123,"uniqueKey":"project_id.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Project ID containing the template. If not provided when using template_slug, the team's default project will be used.","example":123,"uniqueKey":"project_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"project_id","typeLabel":"integer | null"},"template_slug":{"oneOf":[{"type":"string","maxLength":255,"description":"Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.","example":"welcome-email","uniqueKey":"template_slug.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":255,"description":"Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.","example":"welcome-email","uniqueKey":"template_slug.oneOf.1","typeLabel":"null"}],"uniqueKey":"template_slug","typeLabel":"string | null"},"template_version":{"oneOf":[{"type":"integer","minimum":1,"description":"Specific template version to use. If not provided, the active version will be used.","example":1,"uniqueKey":"template_version.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":1,"description":"Specific template version to use. If not provided, the active version will be used.","example":1,"uniqueKey":"template_version.oneOf.1","typeLabel":"null"}],"uniqueKey":"template_version","typeLabel":"integer | null"},"tag":{"type":"string","maxLength":64,"description":"Tag for tracking and analytics. Automatically set from template_slug if not provided.","example":"welcome-series-2024","uniqueKey":"tag","typeLabel":"string"},"metadata":{"type":"object","description":"Custom metadata attached to the email for tracking purposes","additionalProperties":{"type":"string","uniqueKey":"metadata.additionalProperties","typeLabel":"string"},"example":{"user_id":"12345","campaign":"onboarding"},"uniqueKey":"metadata","typeLabel":"object"},"headers":{"type":"object","description":"Custom email headers. Up to 10 headers allowed. Standard envelope headers (From, To, Subject, etc.), SparkPost internal headers (X-MSYS-API), and List-Unsubscribe and List-Unsubscribe-Post headers are managed by the system and cannot be set manually.","maxProperties":10,"additionalProperties":{"type":"string","maxLength":998,"uniqueKey":"headers.additionalProperties","typeLabel":"string"},"example":{"X-Mailer":"MyApp/1.0","X-Custom-ID":"abc-123"},"uniqueKey":"headers","typeLabel":"object"},"substitution_data":{"type":"object","description":"Variables for template substitution in email content","additionalProperties":{"type":"string","uniqueKey":"substitution_data.additionalProperties","typeLabel":"string"},"example":{"first_name":"John","company":"Acme Inc"},"uniqueKey":"substitution_data","typeLabel":"object"},"options":{"type":"object","description":"Email delivery options","properties":{"click_tracking":{"type":"boolean","description":"Enable click tracking for links in the email","uniqueKey":"options.click_tracking","typeLabel":"boolean"},"open_tracking":{"type":"boolean","description":"Enable open tracking via tracking pixel","uniqueKey":"options.open_tracking","typeLabel":"boolean"},"transactional":{"type":"boolean","default":true,"description":"Mark email as transactional (not marketing). **Defaults to `true`.** Transactional mail bypasses unsubscribe suppression, so any send a recipient can opt out of must explicitly set this to `false`.","uniqueKey":"options.transactional","typeLabel":"boolean"},"inline_css":{"type":"boolean","description":"Inline CSS styles in HTML content","uniqueKey":"options.inline_css","typeLabel":"boolean"},"perform_substitutions":{"type":"boolean","description":"Perform variable substitutions in content","uniqueKey":"options.perform_substitutions","typeLabel":"boolean"}},"uniqueKey":"options","typeLabel":"object"},"attachments":{"type":"array","description":"File attachments. When provided, each attachment must include name, type, and data.","items":{"type":"object","description":"Email attachment","required":["name","type","data"],"properties":{"name":{"type":"string","maxLength":255,"description":"Filename of the attachment","example":"invoice.pdf","isRequired":true,"uniqueKey":"attachments.items.[INDEX].name","typeLabel":"string"},"type":{"type":"string","maxLength":255,"description":"MIME type of the attachment","example":"application/pdf","isRequired":true,"uniqueKey":"attachments.items.[INDEX].type","typeLabel":"string"},"data":{"type":"string","pattern":"^[A-Za-z0-9+/=]+$","description":"Base64 encoded file content (no line breaks)","example":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2U=","isRequired":true,"uniqueKey":"attachments.items.[INDEX].data","typeLabel":"string"}},"uniqueKey":"attachments.items.[INDEX]","typeLabel":"object"},"uniqueKey":"attachments","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"minimal":{"title":"minimal","summary":"Minimal request (required fields only)","description":"The absolute minimum required to send an email: from, to, subject, and either html or text content. Subject is required when not using a template.","value":{"from":"sender@example.com","to":["recipient@example.com"],"subject":"Hello","html":"\u003cp>Hello!\u003c/p>"}},"html-and-text":{"title":"html-and-text","summary":"HTML and plain text (recommended)","description":"Sending both HTML and plain text ensures email renders correctly in all email clients.","value":{"from":"sender@example.com","from_name":"Sender Name","to":["recipient@example.com"],"subject":"Welcome to Lettr","html":"\u003ch1>Hello\u003c/h1>\u003cp>Welcome to our service!\u003c/p>","text":"Hello\n\nWelcome to our service!","options":{"click_tracking":true,"open_tracking":true}}},"html-only":{"title":"html-only","summary":"HTML only","description":"Send HTML content only. Some email clients may not render properly without a text fallback.","value":{"from":"sender@example.com","to":["recipient@example.com"],"subject":"Welcome to Lettr","html":"\u003ch1>Hello\u003c/h1>\u003cp>Welcome to our service!\u003c/p>"}},"text-only":{"title":"text-only","summary":"Plain text only","description":"Send plain text content only. Ideal for simple notifications.","value":{"from":"sender@example.com","to":["recipient@example.com"],"subject":"Order Confirmation","text":"Your order #12345 has been confirmed.\n\nThank you for your purchase!"}},"with-attachments":{"title":"with-attachments","summary":"Email with attachments","description":"Send an email with file attachments. Attachments must be base64 encoded.","value":{"from":"billing@example.com","from_name":"Billing Department","to":["customer@example.com"],"subject":"Your Invoice","html":"\u003cp>Please find your invoice attached.\u003c/p>","text":"Please find your invoice attached.","attachments":[{"name":"invoice.pdf","type":"application/pdf","data":"JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2U="}]}},"with-personalization":{"title":"with-personalization","summary":"Personalized email with substitution","description":"Use substitution_data to personalize email content with dynamic variables.","value":{"from":"hello@example.com","from_name":"Acme Inc","to":["john@example.com"],"subject":"Welcome, {{first_name}}!","html":"\u003ch1>Hello {{first_name}}\u003c/h1>\u003cp>Welcome to {{company}}!\u003c/p>","text":"Hello {{first_name}},\n\nWelcome to {{company}}!","substitution_data":{"first_name":"John","company":"Acme Inc"},"metadata":{"user_id":"12345","campaign":"onboarding"}}},"with-template":{"title":"with-template","summary":"Email using a template","description":"Send an email using a pre-defined template. The template's HTML content and subject will be used. You can optionally override the subject.","value":{"from":"hello@example.com","to":["john@example.com"],"template_slug":"welcome-email","substitution_data":{"first_name":"John"}}},"with-template-and-project":{"title":"with-template-and-project","summary":"Email using a template from a specific project","description":"Send an email using a template from a specific project with a specific version. Subject is taken from the template unless explicitly provided.","value":{"from":"hello@example.com","to":["john@example.com"],"project_id":123,"template_slug":"welcome-email","template_version":2,"substitution_data":{"first_name":"John"}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"4fc8a725-d1c7-41f9-96ed-b32c3c83d19f":{"description":"Email queued for delivery. Free tier teams receive quota headers indicating their usage and limits.","headers":{"Idempotency-Replayed":{"description":"Present with value true when SparkPost returns an existing transmission. Quota headers describe current usage before this attempt.","schema":{"type":"string","enum":["true"]}},"X-Monthly-Limit":{"description":"Total monthly email limit for this team. Only present for free tier teams.","schema":{"type":"integer","example":3000}},"X-Monthly-Remaining":{"description":"Remaining emails allowed this month. Only present for free tier teams.","schema":{"type":"integer","example":2500}},"X-Monthly-Reset":{"description":"Unix timestamp when the monthly quota resets (start of next month). Only present for free tier teams.","schema":{"type":"integer","example":1740787200}},"X-Daily-Limit":{"description":"Total daily email limit for this team. Only present for free tier teams.","schema":{"type":"integer","example":100}},"X-Daily-Remaining":{"description":"Remaining emails allowed today. Only present for free tier teams.","schema":{"type":"integer","example":75}},"X-Daily-Reset":{"description":"Unix timestamp when the daily quota resets (tomorrow midnight UTC). Only present for free tier teams.","schema":{"type":"integer","example":1739600000}}},"content":{"application/json":{"schema":{"type":"object","required":["message","data"],"properties":{"message":{"type":"string","description":"Human-readable success message","example":"Email queued for delivery.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"data":{"type":"object","required":["request_id","accepted","rejected"],"properties":{"request_id":{"type":"string","description":"Unique identifier for this email transmission","example":"12345678901234567890","isRequired":true,"uniqueKey":"data.request_id","typeLabel":"string"},"accepted":{"type":"integer","minimum":0,"description":"Number of recipients accepted for delivery","example":1,"isRequired":true,"uniqueKey":"data.accepted","typeLabel":"integer"},"rejected":{"type":"integer","minimum":0,"description":"Number of recipients rejected","example":0,"isRequired":true,"uniqueKey":"data.rejected","typeLabel":"integer"}},"isRequired":true,"uniqueKey":"data","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"message":"Email queued for delivery.","data":{"request_id":"12345678901234567890","accepted":1,"rejected":0}},"examples":{"Example":{"title":"Example","value":{"message":"Email queued for delivery.","data":{"request_id":"12345678901234567890","accepted":1,"rejected":0}}}},"exampleType":"examples"}},"exampleType":"examples"},"983a6290-bb80-4487-83d0-55bc36adad25":{"description":"Failed to send email (domain errors)","content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"invalid_domain":{"title":"invalid_domain","summary":"Invalid sender domain","value":{"message":"The sender domain could not be determined from the email address.","error_code":"invalid_domain"}},"unconfigured_domain":{"title":"unconfigured_domain","summary":"Unconfigured sender domain","value":{"message":"The sender domain is not configured or approved for sending.","error_code":"unconfigured_domain"}}},"exampleType":"examples"}},"exampleType":"examples"},"c5093cb4-680d-4aed-aeb4-529dd7a584ff":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","required":["message"],"description":"Error response for authentication failures (401).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"API key is required.","isRequired":true,"uniqueKey":"message","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"missing_key":{"title":"missing_key","summary":"Missing API key","value":{"message":"API key is required."}},"invalid_key":{"title":"invalid_key","summary":"Invalid API key","value":{"message":"Invalid API key."}}},"exampleType":"examples"}},"exampleType":"examples"},"8bf20a6e-df04-4a40-a8c7-95659635b409":{"description":"Template or project not found","content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"template_not_found":{"title":"template_not_found","summary":"Template not found","value":{"message":"Template with slug 'welcome-email' was not found.","error_code":"template_not_found"}},"project_not_found":{"title":"project_not_found","summary":"Project not found","value":{"message":"Project with ID '123' was not found or you don't have access to it.","error_code":"template_not_found"}},"no_default_project":{"title":"no_default_project","summary":"No default project configured","value":{"message":"No default project is configured for this team.","error_code":"template_not_found"}}},"exampleType":"examples"}},"exampleType":"examples"},"679ca8bb-ad4e-4a9f-b563-fbbcd024d26f":{"description":"SparkPost idempotency conflict: the key was used with a different transmission payload, or the original transmission is still processing.","headers":{"Retry-After":{"description":"Present for idempotency_in_progress. Retry with the same key after this many seconds.","schema":{"type":"integer","example":1}}},"content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"conflict":{"title":"conflict","value":{"message":"This Idempotency-Key was already used with a different request payload.","error_code":"idempotency_key_conflict"}},"in_progress":{"title":"in_progress","value":{"message":"A request with this Idempotency-Key is still processing. Retry with the same key.","error_code":"idempotency_in_progress"}}},"exampleType":"examples"}},"exampleType":"examples"},"9622739b-8c69-482a-a686-54a3c4931479":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["message","error_code","errors"],"properties":{"message":{"type":"string","description":"Human-readable error message","example":"Validation failed.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error code (always `validation_error` for 422 responses)","const":"validation_error","example":"validation_error","isRequired":true,"uniqueKey":"error_code","typeLabel":"string"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string","uniqueKey":"errors.additionalProperties.items.[INDEX]","typeLabel":"string"},"uniqueKey":"errors.additionalProperties","typeLabel":"string[]"},"example":{"from":["The sender email address is required."],"to":["At least one recipient email address is required."]},"isRequired":true,"uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"message":"Validation failed.","error_code":"validation_error","errors":{"from":["The sender email address is required."],"to":["At least one recipient email address is required."]}},"examples":{"Example":{"title":"Example","value":{"message":"Validation failed.","error_code":"validation_error","errors":{"from":["The sender email address is required."],"to":["At least one recipient email address is required."]}}}},"exampleType":"examples"}},"exampleType":"examples"},"d4075786-dcfe-4aaa-9fcf-cc7a90293437":{"description":"Sending quota exceeded. The response includes quota headers to help determine current usage and when the limit resets.","headers":{"X-Monthly-Limit":{"description":"Total monthly email limit for this team.","schema":{"type":"integer","example":3000}},"X-Monthly-Remaining":{"description":"Remaining emails allowed this month (0 when limit is hit).","schema":{"type":"integer","example":0}},"X-Monthly-Reset":{"description":"Unix timestamp when the monthly quota resets (start of next month).","schema":{"type":"integer","example":1740787200}},"X-Daily-Limit":{"description":"Total daily email limit for this team.","schema":{"type":"integer","example":100}},"X-Daily-Remaining":{"description":"Remaining emails allowed today (0 when limit is hit).","schema":{"type":"integer","example":0}},"X-Daily-Reset":{"description":"Unix timestamp when the daily quota resets (tomorrow midnight UTC).","schema":{"type":"integer","example":1739600000}}},"content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"examples":{"monthly_quota_exceeded":{"title":"monthly_quota_exceeded","summary":"Monthly sending quota exceeded","value":{"message":"Sending quota exceeded. Upgrade your plan to continue sending.","error_code":"quota_exceeded"}},"daily_quota_exceeded":{"title":"daily_quota_exceeded","summary":"Daily sending quota exceeded","value":{"message":"Daily sending quota exceeded. Please try again tomorrow.","error_code":"daily_quota_exceeded"}}},"exampleType":"examples"}},"exampleType":"examples"},"19fae837-9f0b-4310-9c0f-b00b58268e7c":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"message":"Failed to send email. Please try again later.","error_code":"send_error"},"examples":{"Example":{"title":"Example","value":{"message":"Failed to send email. Please try again later.","error_code":"send_error"}}},"exampleType":"examples"}},"exampleType":"examples"},"3eb42fc6-f3a2-4095-b988-735e0556c8ba":{"description":"Email transmission failed (upstream provider error). Retry with the same Idempotency-Key so SparkPost can resolve an uncertain outcome without creating a duplicate transmission.","content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"message":"Unconfigured Sending Domain \u003csender.example.com>","error_code":"transmission_failed"},"examples":{"Example":{"title":"Example","value":{"message":"Unconfigured Sending Domain \u003csender.example.com>","error_code":"transmission_failed"}}},"exampleType":"examples"}},"exampleType":"examples"},"4ff669d0-12ed-49b1-9ac2-413ada730cf6":{"description":"Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":5}}},"content":{"application/json":{"schema":{"type":"object","required":["message","error_code"],"description":"Error response for non-validation errors (400, 409, 500, 502).","properties":{"message":{"type":"string","description":"Human-readable error message","example":"The sender domain could not be determined from the email address.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"error_code":{"type":"string","description":"Error codes returned by the API.\n\n| Code | HTTP Status | Description |\n|------|-------------|-------------|\n| `validation_error` | 422 | Request validation failed. Check the `errors` object for field-specific messages. |\n| `invalid_domain` | 400 | The sender domain could not be determined from the email address. |\n| `unconfigured_domain` | 400 | The sender domain is not configured or approved for sending. |\n| `send_error` | 400, 500 | General error during email send preparation or domain registration. |\n| `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g., sandbox key without associated user, upstream error). |\n| `internal_error` | 500 | An unexpected error on our side. The `message` names what failed; retry later. |\n| `transmission_failed` | 502 | Email transmission to the upstream provider failed. |\n| `resource_already_exists` | 409 | The resource (e.g., domain) already exists. |\n| `not_found` | 404 | The specified resource was not found. |\n| `template_not_found` | 404 | The specified template, project, or template version was not found. |\n| `insufficient_scope` | 403 | The API key does not have the required scope for this endpoint. |\n| `domain_not_allowed` | 403 | The sender domain is not in the API key's allowed sender domains. |\n| `schedule_cancellation_failed` | 409, 500 | The scheduled email can no longer be cancelled (already sent, already cancelled, or being injected right now), or the cancellation itself failed. |\n| `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your plan to continue sending. |\n| `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again tomorrow. |\n| `campaign_not_sendable` | 422 | The campaign cannot be sent in its current state (not a draft, or missing subject/sender/content). |\n| `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it cannot be unscheduled. |","enum":["validation_error","idempotency_key_conflict","idempotency_in_progress","invalid_domain","unconfigured_domain","send_error","retrieval_error","internal_error","transmission_failed","resource_already_exists","not_found","template_not_found","insufficient_scope","domain_not_allowed","schedule_cancellation_failed","quota_exceeded","daily_quota_exceeded","campaign_not_sendable","campaign_not_scheduled"],"example":"invalid_domain","isRequired":true,"uniqueKey":"error_code","typeLabel":"enum\u003cstring>"}},"uniqueKey":"","typeLabel":"object"},"example":{"message":"Unable to verify your API key right now. Please retry shortly.","error_code":"auth_unavailable"},"examples":{"Example":{"title":"Example","value":{"message":"Unable to verify your API key right now. Please retry shortly.","error_code":"auth_unavailable"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"42617010-5738-4e0f-95ed-272f074cfd32":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key for authentication","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"3a9a6297-5f46-49ab-955a-fb22c45ca41c":{"url":"https://app.lettr.com/api","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"API key for authentication","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"API key for authentication","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"openapi.json"},"subdomain":"lettr","siteName":"Lettr","title":"Send Email - Lettr","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-22T13:17:28.340Z","originalFileLocation":"api-reference/emails/send-email.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Lettr\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Send Email - Lettr\">\u003cmeta data-mint-head property=\"og:description\" content=\"Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Lettr\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.lettr.com/api-reference/emails/send-email\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://lettr.mintlify.site/_mintlify/api/og/v2?division=Emails\u0026amp;title=Send+Email\u0026amp;description=Send+a+transactional+email+with+optional+attachments%2C+tracking%2C+and+personalization.+At+least+one+of+%60html%60+or+%60text%60+content+must+be+provided.+Supply+%60Idempote\u0026amp;theme=6d36e4ae9c92b67d8136c8c1\u0026amp;signature=c8f14605d893d706468ee98ad00c4e9b61da8da304ce51e6892a106058bebda8\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Send Email - Lettr\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://lettr.mintlify.site/_mintlify/api/og/v2?division=Emails\u0026amp;title=Send+Email\u0026amp;description=Send+a+transactional+email+with+optional+attachments%2C+tracking%2C+and+personalization.+At+least+one+of+%60html%60+or+%60text%60+content+must+be+provided.+Supply+%60Idempote\u0026amp;theme=6d36e4ae9c92b67d8136c8c1\u0026amp;signature=c8f14605d893d706468ee98ad00c4e9b61da8da304ce51e6892a106058bebda8\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/lettr/dSsCtMUFma4ICJBo/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Lettr\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#EC104B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.lettr.com/api-reference/emails/send-email\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/emails/send-email.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.lettr.com/#organization\",\"name\":\"Lettr\",\"url\":\"https://docs.lettr.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/lettr/w6cQMnBCGTvjJ4__/logo/light.svg?fit=max\u0026auto=format\u0026n=w6cQMnBCGTvjJ4__\u0026q=85\u0026s=2cad5a94a80e61999cf9feaeac06e9c6\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.lettr.com#website\",\"name\":\"Lettr\",\"url\":\"https://docs.lettr.com\",\"publisher\":{\"@id\":\"https://docs.lettr.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.lettr.com/api-reference/emails/send-email#webpage\",\"url\":\"https://docs.lettr.com/api-reference/emails/send-email\",\"name\":\"Send Email\",\"description\":\"Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\",\"dateModified\":\"2026-09-22T13:17:28.340Z\",\"isPartOf\":{\"@id\":\"https://docs.lettr.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.lettr.com/api-reference/emails/send-email#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.lettr.com/api-reference/emails/send-email#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Lettr\",\"item\":\"https://docs.lettr.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Send Email\",\"item\":\"https://docs.lettr.com/api-reference/emails/send-email\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.lettr.com/api-reference/emails/send-email#apireference\",\"headline\":\"Send Email\",\"name\":\"Send Email\",\"description\":\"Send a transactional email with optional attachments, tracking, and personalization. At least one of html or text content must be provided. Supply Idempotency-Key for safe retries using SparkPost native transmission idempotency. Keys are namespaced per Lettr API key and retained by SparkPost for 24 hours. Repeating the same transmission payload returns its original result without another delivery; conflicting payloads or in-progress transmissions return 409. Retry transport failures with the same key. Lettr still validates authorization, domains and sending quota before contacting SparkPost, so an exhausted quota returns 429 even for a retry. Replayed responses do not increment sending counters again. Requests without this header are sent independently.\",\"url\":\"https://docs.lettr.com/api-reference/emails/send-email\",\"mainEntityOfPage\":{\"@id\":\"https://docs.lettr.com/api-reference/emails/send-email#webpage\"},\"dateModified\":\"2026-09-22T13:17:28.340Z\",\"publisher\":{\"@id\":\"https://docs.lettr.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.lettr.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Lettr\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Lettr\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/emails/send-email.md","siteName":"Lettr","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"title":"Introduction","href":"/api-reference/introduction"},{"title":"Rate Limit","description":"Understand Lettr's per-team API rate limits, daily and monthly sending quotas, and the response headers that track your usage in real time.","href":"/api-reference/rate-limit"}]},{"group":"Emails","pages":[{"title":"Send Email","openapi":"POST /emails","href":"/api-reference/emails/send-email"},{"title":"Get Email Detail","openapi":"GET /emails/{requestId}","description":"Retrieve all events for a specific sent email by its request ID. Returns delivery, bounce, open, click, and other events in reverse chronological order. If no `from` date is provided, defaults to the last 10 days.","href":"/api-reference/emails/get-email-detail"},{"title":"List Email Events","openapi":"GET /emails/events","href":"/api-reference/emails/list-email-events"}]},{"group":"Scheduled Emails","pages":[{"title":"Schedule Email","openapi":"POST /emails/scheduled","href":"/api-reference/emails/schedule-email"},{"title":"List Scheduled Emails","openapi":"GET /emails/scheduled","href":"/api-reference/emails/list-scheduled-emails"},{"title":"Get Scheduled Email","openapi":"GET /emails/scheduled/{transmissionId}","href":"/api-reference/emails/get-scheduled-email"},{"title":"Cancel Scheduled Email","openapi":"DELETE /emails/scheduled/{transmissionId}","href":"/api-reference/emails/cancel-scheduled-email"}]},{"group":"Domains","pages":[{"title":"List Domains","openapi":"GET /domains","href":"/api-reference/domains/list-domains"},{"title":"Create Domain","openapi":"POST /domains","href":"/api-reference/domains/create-domain"},{"title":"Get Domain","openapi":"GET /domains/{domain}","href":"/api-reference/domains/get-domain"},{"title":"Delete Domain","openapi":"DELETE /domains/{domain}","href":"/api-reference/domains/delete-domain"},{"title":"Verify Domain","openapi":"POST /domains/{domain}/verify","href":"/api-reference/domains/verify-domain"}]},{"group":"Templates","pages":[{"title":"List Templates","openapi":"GET /templates","href":"/api-reference/templates/list-templates"},{"title":"Create Template","openapi":"POST /templates","href":"/api-reference/templates/create-template"},{"title":"Get Template","openapi":"GET /templates/{slug}","href":"/api-reference/templates/get-template"},{"title":"Update Template","openapi":"PUT /templates/{slug}","href":"/api-reference/templates/update-template"},{"title":"Delete Template","openapi":"DELETE /templates/{slug}","href":"/api-reference/templates/delete-template"},{"title":"Get Merge Tags","openapi":"GET /templates/{slug}/merge-tags","href":"/api-reference/templates/get-merge-tags"},{"title":"List Folders","openapi":"GET /folders","href":"/api-reference/templates/list-folders"}]},{"group":"Webhooks","pages":[{"title":"List Webhooks","openapi":"GET /webhooks","href":"/api-reference/webhooks/list-webhooks"},{"title":"Create Webhook","openapi":"POST /webhooks","href":"/api-reference/webhooks/create-webhook"},{"title":"Get Webhook","openapi":"GET /webhooks/{webhookId}","href":"/api-reference/webhooks/get-webhook"},{"title":"Update Webhook","openapi":"PUT /webhooks/{webhookId}","href":"/api-reference/webhooks/update-webhook"},{"title":"Delete Webhook","openapi":"DELETE /webhooks/{webhookId}","href":"/api-reference/webhooks/delete-webhook"}]},{"group":"System","pages":[{"title":"Health Check","openapi":"GET /health","href":"/api-reference/system/health-check"},{"title":"Auth Check","openapi":"GET /auth/check","href":"/api-reference/system/auth-check"}]},{"group":"Campaigns","pages":[{"title":"Create a campaign","openapi":"POST /campaigns","href":"/api-reference/campaigns/create-a-campaign"},{"title":"List campaigns","openapi":"GET /campaigns","href":"/api-reference/campaigns/list-campaigns"},{"title":"Show a campaign","openapi":"GET /campaigns/{campaignId}","href":"/api-reference/campaigns/show-a-campaign"},{"title":"List campaign engagement events","openapi":"GET /campaigns/{campaignId}/events","href":"/api-reference/campaigns/list-campaign-engagement-events"},{"title":"Send a campaign now","openapi":"POST /campaigns/{campaignId}/send","href":"/api-reference/campaigns/send-a-campaign-now"},{"title":"Schedule a campaign","openapi":"POST /campaigns/{campaignId}/schedule","href":"/api-reference/campaigns/schedule-a-campaign"},{"title":"Unschedule a campaign","openapi":"POST /campaigns/{campaignId}/unschedule","href":"/api-reference/campaigns/unschedule-a-campaign"}]},{"group":"Audience Lists","pages":[{"title":"List audience lists","openapi":"GET /audience/lists","href":"/api-reference/audience/list-audience-lists"},{"title":"Create an audience list","openapi":"POST /audience/lists","href":"/api-reference/audience/create-an-audience-list"},{"title":"Bulk delete audience lists","openapi":"DELETE /audience/lists/bulk","href":"/api-reference/audience/bulk-delete-audience-lists"},{"title":"Show an audience list","openapi":"GET /audience/lists/{listId}","href":"/api-reference/audience/show-an-audience-list"},{"title":"Update an audience list","openapi":"PATCH /audience/lists/{listId}","href":"/api-reference/audience/update-an-audience-list"},{"title":"Delete an audience list","openapi":"DELETE /audience/lists/{listId}","href":"/api-reference/audience/delete-an-audience-list"}]},{"group":"Audience Contacts","pages":[{"title":"List audience contacts","openapi":"GET /audience/contacts","href":"/api-reference/audience/list-audience-contacts"},{"title":"Create a contact","openapi":"POST /audience/contacts","href":"/api-reference/audience/create-a-contact"},{"title":"Bulk create contacts","openapi":"POST /audience/contacts/bulk","href":"/api-reference/audience/bulk-create-contacts"},{"title":"Bulk attach contacts to lists","openapi":"POST /audience/contacts/lists/bulk","href":"/api-reference/audience/bulk-attach-contacts-to-lists"},{"title":"Bulk detach contacts from lists","openapi":"DELETE /audience/contacts/lists/bulk","href":"/api-reference/audience/bulk-detach-contacts-from-lists"},{"title":"Bulk subscribe contacts to topics","openapi":"POST /audience/contacts/topics/bulk","href":"/api-reference/audience/bulk-subscribe-contacts-to-topics"},{"title":"Bulk unsubscribe contacts from topics","openapi":"DELETE /audience/contacts/topics/bulk","href":"/api-reference/audience/bulk-unsubscribe-contacts-from-topics"},{"title":"Show a contact","openapi":"GET /audience/contacts/{contactId}","href":"/api-reference/audience/show-a-contact"},{"title":"Update a contact","openapi":"PATCH /audience/contacts/{contactId}","href":"/api-reference/audience/update-a-contact"},{"title":"Delete a contact","openapi":"DELETE /audience/contacts/{contactId}","href":"/api-reference/audience/delete-a-contact"},{"title":"Attach contact to list","openapi":"POST /audience/contacts/{contactId}/lists/{listId}","href":"/api-reference/audience/attach-contact-to-list"},{"title":"Detach contact from list","openapi":"DELETE /audience/contacts/{contactId}/lists/{listId}","href":"/api-reference/audience/detach-contact-from-list"},{"title":"Subscribe contact to topic","openapi":"POST /audience/contacts/{contactId}/topics/{topicId}","href":"/api-reference/audience/subscribe-contact-to-topic"},{"title":"Unsubscribe contact from topic","openapi":"DELETE /audience/contacts/{contactId}/topics/{topicId}","href":"/api-reference/audience/unsubscribe-contact-from-topic"}]},{"group":"Audience Topics","pages":[{"title":"List audience topics","openapi":"GET /audience/topics","href":"/api-reference/audience/list-audience-topics"},{"title":"Create a topic","openapi":"POST /audience/topics","href":"/api-reference/audience/create-a-topic"},{"title":"Show a topic","openapi":"GET /audience/topics/{topicId}","href":"/api-reference/audience/show-a-topic"},{"title":"Update a topic","openapi":"PATCH /audience/topics/{topicId}","href":"/api-reference/audience/update-a-topic"},{"title":"Delete a topic","openapi":"DELETE /audience/topics/{topicId}","href":"/api-reference/audience/delete-a-topic"}]},{"group":"Audience Properties","pages":[{"title":"List audience properties","openapi":"GET /audience/properties","href":"/api-reference/audience/list-audience-properties"},{"title":"Create a property","openapi":"POST /audience/properties","href":"/api-reference/audience/create-a-property"},{"title":"Show a property","openapi":"GET /audience/properties/{propertyId}","href":"/api-reference/audience/show-a-property"},{"title":"Update a property","openapi":"PATCH /audience/properties/{propertyId}","href":"/api-reference/audience/update-a-property"},{"title":"Delete a property","openapi":"DELETE /audience/properties/{propertyId}","href":"/api-reference/audience/delete-a-property"}]},{"group":"Audience Segments","pages":[{"title":"List audience segments","openapi":"GET /audience/segments","href":"/api-reference/audience/list-audience-segments"},{"title":"Create a segment","openapi":"POST /audience/segments","href":"/api-reference/audience/create-a-segment"},{"title":"Show a segment","openapi":"GET /audience/segments/{segmentId}","href":"/api-reference/audience/show-a-segment"},{"title":"Update a segment","openapi":"PATCH /audience/segments/{segmentId}","href":"/api-reference/audience/update-a-segment"},{"title":"Delete a segment","openapi":"DELETE /audience/segments/{segmentId}","href":"/api-reference/audience/delete-a-segment"}]}]},{"tab":"Knowledge Base","pages":[{"title":"Knowledge Base","href":"/knowledge-base/introduction"}]}]},"basePath":"","title":"Send Email - Lettr","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B6WFFOBL.js","utils-BN5um1KA.js","cloneDeep-C3md22mN.js","_Uint8Array-DLlL8L26.js","isObject-FP1Yky1u.js","utils-BSmbkXJR.js","addUniqueKeysToSchema-2tqcVnUE.js","snippetPresets-CtWfvr2J.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DkKHBy30.js","isEqual-O3q7y6pq.js","usePlaygroundInputsStore-Brc5H9UJ.js","shallow-C4L4xvbs.js","getApiPlaygroundDisplay-2bxyq_aI.js","CodeSnippet-BJu8ddd5.js","CodeSnippets-dazWmoqB.js","Page-CnLhKuUV.js","getPastedJson-Chy3Qa1S.js","icon-CyO7h3jh.js","MethodPill-Dle0_91v.js","DuplicateIcon-CVvWAf4a.js","createIcon-Di07A27B.js","DynamicMarkdown-C4w9kavL.js","SectionHeading-XiBebVYC.js","axios-vUo_bRtp.js","Markdown-DTeL0SpS.js","dist-OCScizqf.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","katex-YMM-FMeD.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","AssistantPageLink-KcneGfMY.js"]}