Emails

Send Email

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.

post/emails

Request

  • Base URL: https://app.lettr.com/api
  • URL: https://app.lettr.com/api/emails
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

fromstring email required

Sender email address

from_namestring nullable

Sender display name

subjectstring nullable

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.

tostring[] required

Recipient email addresses

ccstring[]

Carbon copy recipient email addresses

bccstring[]

Blind carbon copy recipient email addresses

reply_tostring email nullable

Reply-To email address

reply_to_namestring nullable

Reply-To display name

htmlstring nullable

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.

textstring nullable

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.

amp_htmlstring nullable

AMP HTML content for supported email clients

project_idinteger nullable

Project ID containing the template. If not provided when using template_slug, the team's default project will be used.

template_slugstring nullable

Template slug to use for email content. When provided, the template's HTML will be used instead of the html field.

template_versioninteger nullable

Specific template version to use. If not provided, the active version will be used.

tagstring

Tag for tracking and analytics. Automatically set from template_slug if not provided.

metadataobject

Custom metadata attached to the email for tracking purposes

headersobject

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.

substitution_dataobject

Variables for template substitution in email content

Example request

{
  "from": "sender@example.com",
  "from_name": "Sender Name",
  "subject": "Welcome to Lettr",
  "to": [
    "recipient@example.com"
  ],
  "cc": [
    "cc@example.com"
  ],
  "bcc": [
    "bcc@example.com"
  ],
  "reply_to": "reply@example.com",
  "reply_to_name": "Reply Name",
  "html": "<h1>Hello</h1><p>Welcome!</p>",
  "text": "Hello\n\nWelcome!",
  "project_id": 123,
  "template_slug": "welcome-email",
  "template_version": 1,
  "tag": "welcome-series-2024",
  "metadata": {
    "user_id": "12345",
    "campaign": "onboarding"
  },
  "headers": {
    "X-Mailer": "MyApp/1.0",
    "X-Custom-ID": "abc-123"
  },
  "substitution_data": {
    "first_name": "John",
    "company": "Acme Inc"
  },
  "attachments": [
    {
      "name": "invoice.pdf",
      "type": "application/pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2U="
    }
  ]
}

Response

Email queued for delivery. Free tier teams receive quota headers indicating their usage and limits.

messagestring required

Human-readable success message

Example response

{
  "message": "Email queued for delivery.",
  "data": {
    "request_id": "12345678901234567890",
    "accepted": 1
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.