v1

latestOpenAPI 3.0.02026-07-2411724301.7 KB

Send a single email

Send one email payload to one or more recipients (To/CC/BCC). Attachments supported; total payload ≤ 20 MB.

post/v2/{sid}/email/messages

Path parameters

sidstring required

Example:HXAP16XXXXXX97IN

Kaleyra Account SID (e.g., HXAP16XXXXXX97IN).

Headers

api-keystring required

Example:Ac4XXXXX21f

API Key generated by kaleyra.io. Example - Ac4XXXXX21f

Content-Typestring required

The format in which the data is sent.

Request body

fromstring required

Sender email address; domain must be whitelisted on your account.

from_namestring

Display name shown to recipients.

tostring required

Comma-separated list of recipients (max 50 addresses).

ccstring

Comma-separated CC recipients (max 50 addresses).

bccstring

Comma-separated BCC recipients (max 50 addresses).

subjectstring

Email subject. When using templates, the API subject overrides the template subject if present.

tagstring

Category/label for the email (for reporting/segmentation).

type'OTP' | 'MKT' | 'TXN'

Email type; defaults to MKT if omitted.

priorityinteger

Send priority (implementation-specific; higher values may be processed first).

html_bodystring

HTML content of the message (≤ ~5 MB). Preferred for tracking.

html_contentstring

Plain-text body companion to html_body (e.g. multipart/alternative text part). Distinct from text_body in some integrations.

text_bodystring

Plain text content (≤ ~5 MB). Used by clients that don’t support HTML.

reply_tostring

Reply-to address to receive responses.

dynamic_contentboolean

Set true to enable params substitution in subject/body (use {{key}} placeholders).

paramsobject

Key-value pairs for dynamic substitution (≤ 20 keys; key ≤ 20 chars; value ≤ 4000 chars).

callback_profile_idstring

Callback profile ID configured for webhook notifications.

refstring

Optional contextual reference (e.g., campaign name).

ref1string

Optional contextual reference (e.g., customer ID).

ref2string

Optional contextual reference.

ref3string

Optional third contextual reference (e.g. segment or batch id).

template_idstring

Template ID to use; API fields override template fields where present.

template_namestring

Name of a saved template to use (alternative to template_id). API fields override template fields where present.

webhook_idstring

Optional webhook identifier if supported on your account.

metadataobject

Free-form metadata echoed in logs/callbacks (if enabled).

Example request

{
  "from": "no-reply@kaleyra.com",
  "from_name": "No Reply Email from Kaleyra",
  "to": "john.d@example.com,jack.l@example.com",
  "cc": "liz.r@example.com",
  "bcc": "bean.d@example.com",
  "subject": "Sample Email from API",
  "tag": "Invitation",
  "type": "MKT",
  "priority": 1,
  "html_body": "<b>Hello</b>",
  "html_content": "Hello, welcome!",
  "text_body": "Hello",
  "reply_to": "replyto@kaleyra.com",
  "dynamic_content": true,
  "params": {
    "username": "Tom",
    "quantity": "50",
    "dMarketValue": "819167.0000",
    "subjectBrandName": "samplebrandname"
  },
  "attachments": [
    {
      "content": "https://github.com/kaleyra/kaleyrapython/blob/master/requirements.txt",
      "content_type": "text/plain",
      "filename": "requirements.txt"
    }
  ],
  "callback_profile_id": "xxxxx_850bxx8a-bdc2-4axx-a0bd-xxa2b1b176d1",
  "ref": "campaign2",
  "ref1": "companyID",
  "ref2": "productname",
  "ref3": "segment_789",
  "template_id": "6ffbe894-d0c2-4159-9f54-26ca774f1a06",
  "template_name": "email-test-28",
  "metadata": {
    "quantity": "5000",
    "dMarketValue": "8167.00",
    "symbol": "PMBND"
  }
}

Response

Request accepted; messages queued for delivery.

errorobject nullable

Error details, if any (usually empty on success).

Example response

{
  "data": [
    {
      "message_id": "xxxxx56e-3be8-49ad-9fd9-xxxxx4b452f3:1",
      "to": "recipient@gmail.com,recipient1@gmail.com",
      "from": "sender@gmail.com",
      "subject": "subject"
    }
  ],
  "error": {}
}