Send a transactional email

POST

/api/v3/transactionals/actions/send

Sends a single, event-driven transactional email (password reset, receipt, welcome, etc.) through a channel for sender identity, tagged by transactional type for metric rollups.

Authorization: Bearer token (company-level API key). The caller must be a company administrator for the channel’s owning company.

Feature flags: Requires both companyAudienceSending and transactionalEmail to be enabled.

Rate limit: 120 sends per minute, per company. Exceeding the cap returns 429 Too Many Requests.

Behavior: Creates a private, tagged Letter and immediately queues the send. The Letter’s uniqueId is used as the SparkPost campaignId, so engagement events aggregate through the standard metrics pipeline while the Letter stays out of newsletter listings and metrics. If the recipient matches a known contact, their profile data enriches substitutionData — caller-supplied values win on key conflicts.

Success: 200 OK — items.uniqueId is the created Letter’s id (and the SparkPost campaignId); items.to echoes the recipient.

Authorizations

bearerAuth

Request Body

application/json

Examples

Send a transactional email

{
    "api": true,
    /**
     * The channel you send through (used for sender identity). Channel slug.
     */
    "channel": "an-example-channel",
    /**
     * The recipient's email address.
     */
    "to": "[email protected]",
    /**
     * (optional) The recipient's display name. Max 191 chars.
     */
    "toName": "Jane Doe",
    /**
     * The email subject. Max 191 chars; must contain a non-whitespace character.
     */
    "subject": "Your password reset link",
    /**
     * The full HTML body of the email. Bring your own HTML.
     */
    "html": "<!DOCTYPE html><html><body><h1>Reset your password</h1><p><a href=\"https://example.com/reset\">Reset now</a></p></body></html>",
    /**
     * (optional) Key/value merge data interpolated into the HTML at send time.
     * Caller-supplied values take precedence over any contact-profile enrichment.
     */
    "substitutionData": {
        "firstName": "Jane",
        "resetUrl": "https://example.com/reset"
    },
    /**
     * Transactional type tags, used for metric rollups. Required: 1-20 items,
     * each 60 chars or fewer. Trimmed and de-duplicated case-insensitively.
     */
    "tags": ["password-reset"]
}

Responses

200

200 OK

application/json

object

items

object

string

uniqueId

string

message

string

total

number

Examples

200 OK

{
  "items": {
    "to": "[email protected]",
    "uniqueId": "6cuswtvr7p"
  },
  "message": "Your transactional email will be sent shortly.",
  "total": 0
}

Still can’t find what you need? Contact support.