Sending Email¶

Send an email to one recipient using a subject and HTML content. This service is available in API 3.2 and uses the email route configured for your account.

URL: base/Message/SendEmail
Method: POST
Content-Type: application/json

Here, base is your allocated HTTPS API endpoint including /v3.2. The full route is POST /v3.2/Message/SendEmail, without an /api prefix. See Getting Started for the base URL convention.

Use the Scalar API 3.2 reference alongside this guide.

Authentication and setup¶

Use a Basic Access Token or HMAC authentication as described in Security. The authenticated account must have one of the sa, Admin, or Organization roles.

Your account needs an email route and an approved sender configured before sending. From is used as the source for route selection. The actual sender address, sender name, and reply-to address depend on the configured email route; supplying From does not override those settings.

Request¶

This example tests routing without sending an email. Set Test to false, or omit it, when you are ready to send.

{
  "To": "recipient@example.com",
  "From": "no-reply@example.com",
  "Subject": "Your survey invitation",
  "Content": "<p>Hello,</p><p>Please <a href=\"https://example.com/survey\">complete our survey</a>.</p>",
  "Test": true,
  "Lookup": false
}

Parameters¶

Name	Type	Required / default	Description
`To`	string	Required	The recipient email address. Supply one address per request.
`From`	string	Required	The source value used to select your configured email route. Use the sender agreed for your account.
`Subject`	string	Required	The email subject. Must not be empty.
`Content`	string	Required	The email body. Must not be empty. HTML is supported; the current email gateways also derive a plain-text alternative from this content.
`When`	string (date-time)	Optional; current UTC time	Requested send time, subject to your account and route settings. Use an ISO 8601 UTC value, for example `2026-12-01T09:00:00Z`. Omit it to send immediately.
`Test`	boolean	Optional; `false`	If `true`, checks that a route can be found without submitting the email to the gateway. This does not test provider acceptance or mailbox delivery.
`Lookup`	boolean	Optional; `false`	Leave `false` or omit for email. This inherited option invokes telephone-number lookup, not email-address validation.
`MetaData`	array of objects	Optional	Additional values associated with the message. See Metadata and callbacks.
`Callback`	array of objects	Optional	Per-request callback settings. See Metadata and callbacks.

The required strings are checked for missing or empty values. The request model does not validate email-address syntax; supply valid addresses before submitting.

The endpoint selects the email message type automatically. Fields from the SMS request such as Destination, Source, Message, Reply, Window, Timeout, Type, OnBehalf, and SurveyId are not email request options. CC, BCC, attachments, and separate plain-text bodies are not exposed by this service.

cURL example¶

Set API_BASE_URL to your allocated HTTPS base URL including /v3.2, and DIY_API_TOKEN to your Basic Access Token.

curl --request POST "${API_BASE_URL}/Message/SendEmail" \
  --header "Authorization: Basic ${DIY_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "To": "recipient@example.com",
    "From": "no-reply@example.com",
    "Subject": "Email routing test",
    "Content": "<p>This request checks the configured email route.</p>",
    "Test": true,
    "Lookup": false
  }'

Metadata and callbacks¶

Supply MetaData and Callback directly at the top level of the JSON request, alongside To and Subject. Use those exact property names: these extension fields are case-sensitive. Do not wrap them in an additional metadata object.

{
  "To": "recipient@example.com",
  "From": "no-reply@example.com",
  "Subject": "Your survey invitation",
  "Content": "<p>Please complete our survey.</p>",
  "Test": true,
  "Lookup": false,
  "MetaData": [
    { "RequestID": "email-2026-001" },
    { "Campaign": "customer-feedback" }
  ],
  "Callback": [
    { "Url": "https://example.com/api/message-status" },
    { "Timeout": 2000 },
    { "TotalTimeout": 30000 },
    { "Retries": 3 },
    { "Method": "POST" },
    { "ContentType": "application/json" }
  ]
}

Request metadata is merged with any metadata configured on the access token. Avoid conflicting names.

The generated schema may not list MetaData and Callback as named properties because the email model accepts them as JSON extension data. See Web Hooks and Callbacks for callback settings. Callback events depend on the configured route and provider integration. A routing test does not send an email or exercise delivery callbacks.

The current implementation ignores an invalid Callback block, so a successful send response does not prove the callback configuration is valid. Check that the expected events reach your endpoint during integration testing.

Responses¶

Accepted for routing¶

A successful non-test request returns HTTP 200. For example, when a message transaction is created:

{
  "MessageID": "MS123456789",
  "Status": "Sent",
  "Carrier": "Unknown",
  "Reachable": true,
  "NumberType": "Unknown"
}

Delivery tracking

Status: "Sent" means the API handed the message to the configured routing service. It does not confirm provider acceptance, inbox delivery, or that the recipient has read the email. Use the available delivery events to track later progress.

Name	Description
`MessageID`	DIY Surveys message ID, prefixed with `MS`, when a routing transaction is available. Otherwise `Unknown`.
`Status`	`Sent` after successful routing.
`Carrier`	A shared messaging response field; normally `Unknown` for email.
`Reachable`	Initially `true`; this is not a mailbox-validity or delivery check.
`NumberType`	A shared messaging response field; normally `Unknown` for email.

Successful routing test¶

With Test: true, the service also returns HTTP 200 and Status: "Sent", but no email is submitted and no message transaction is created:

{
  "MessageID": "Unknown",
  "Status": "Sent",
  "Carrier": "Unknown",
  "Reachable": true,
  "NumberType": "Unknown"
}

HTTP statuses and errors¶

Status	Meaning
`200`	Routing succeeded, or a routing test found a route.
`400`	Request validation failed, metadata could not be processed, a destination was blocked by a stop-list check, or the email could not be routed.
`401`	Authentication is missing or invalid.
`403`	The authenticated account does not have a permitted role.

Missing required fields or invalid field types produce a validation error response. Error bodies are not all the same shape: controller failures can return a text message, while a stop-list rejection returns the shared response object.

The controller uses these error messages:

There was a problem with the MetaData value
unable to route email

A stop-list rejection returns HTTP 400 with:

{
  "MessageID": "Unknown",
  "Status": "Blocked",
  "Carrier": "Unknown",
  "Reachable": false,
  "NumberType": "Unknown"
}

For routing failures, check the account email route and sender configuration with DIY Surveys support.