Transactional emails are event-driven emails triggered automatically by an application when a specific event occurs. Examples include order confirmations, payment receipts, password-related notifications, account notifications, booking confirmations, and other emails that contain information specific to an individual user or transaction.

How Transactional Email Works

The transactional email flow is:

Your Application → Rollout Email API → Event Identifier → Transactional Campaign → Email Template → SMTP → Recipient

For example:

Your application
      ↓
payment-success
      ↓
Rollout Email
      ↓
Transactional Campaign
      ↓
Payment Receipt Template
      ↓
SMTP
      ↓
customer@example.com

Transactional campaigns are event-driven and do not use the normal campaign audience selection or scheduled delivery workflow. The campaign form specifically identifies the transactional campaign type as Transactional (Event-Driven API), and the audience and scheduling sections are not used for this campaign type.

Creating a Transactional Campaign

Before your application can trigger a transactional email, create and configure a transactional campaign.

Step 1: Create the Campaign

1. Go to Campaigns → All Campaign.

2. Click New campaign.

3. Enter a Campaign Name.

For example:

Payment Receipt

Step 2: Select the Campaign Type

Set Type to:

Transactional (Event-Driven API)

The transactional campaign type is specifically designed to be triggered through the API.

Step 3: Set the API Event Name Hook

Enter an API Event Name Hook.

For example:

payment-success

This value is important because your application must send the exact same event identifier when triggering the API.

For example:

payment-success

and:

Payment-Success

should not be treated as the same event identifier. Use the exact value configured in the campaign.

The event identifier is required for transactional campaigns and is used to locate the active transactional campaign associated with the API request.

Step 4: Select an Email Template

Select the Email Template that should be sent when the event is triggered.

For example:

Payment Receipt Template

The template is required when creating the campaign.

Step 5: Set the Campaign Status

Set the campaign Status to:

Active

Only an active transactional campaign can be triggered through the transactional API.

Step 6: Configure SMTP

In Delivery & SMTP, assign at least one SMTP Delivery Profile to the campaign.

Configure:

• SMTP Delivery Profile

• Batch Speed

• Total Limit

The campaign can have multiple SMTP profiles, allowing the campaign's configured SMTP delivery setup to be used for sending.

Example Transactional Campaign

A payment receipt campaign could be configured as follows:

Once this campaign is active, your application can trigger it by sending a request containing the payment-success event identifier.

Triggering a Transactional Email

Transactional emails are triggered using the Rollout Email API.

The API endpoint is:

POST /api/v1/transactional/send

The request must be authenticated using your Rollout Email API authentication mechanism.

Basic Request

A basic request contains:

• event_identifier

• email

• first_name

• variables

The email address and event identifier are required. first_name and variables are optional.

Example Request

{
    "event_identifier": "payment-success",
    "email": "customer@example.com",
    "first_name": "John",
    "variables": {
        "order_id": "ORD-10025",
        "amount": "$149.00",
        "product_name": "Premium Plan"
    }
}

The event_identifier must match the API Event Name Hook configured on the transactional campaign.

Example cURL Request

curl -X POST "https://rolloutemail.com/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "event_identifier": "payment-success",
    "email": "customer@example.com",
    "first_name": "John",
    "variables": {
      "order_id": "ORD-10025",
      "amount": "$149.00",
      "product_name": "Premium Plan"
    }
  }'

Replace YOUR_API_TOKEN with the authentication credential used by your Rollout Email API integration.

Passing Dynamic Data

Transactional emails become particularly useful when the email needs to contain information that changes for every recipient.

For example, the same Payment Receipt template can be used for thousands of customers while each email contains that customer's:

• Name

• Email address

• Phone number

• Order number

• Payment amount

• Product name

• Product image

• Invoice number

• Transaction date

• Subscription name

• Company name

• Other application-specific information

Dynamic information is passed through the variables object in the API request. The API accepts variables as an optional array and passes the supplied values to the transactional email job.

Example with Customer and Order Data

{
    "event_identifier": "order-confirmed",
    "email": "john@example.com",
    "first_name": "John",
    "variables": {
        "name": "John Doe",
        "phone_number": "+1 555 123 4567",
        "order_id": "ORD-10452",
        "amount": "$249.00",
        "product_name": "Premium Subscription",
        "product_image": "https://example.com/images/premium-plan.jpg"
    }
}

Your application can construct these values from its own database when the event occurs.

Example: Order Confirmation

Suppose your application has just received a successful order.

Your database contains:

Customer: John Doe
Email: john@example.com
Phone: +1 555 123 4567
Order: ORD-10452
Amount: $249.00
Product: Premium Subscription
Product Image: https://example.com/images/premium-plan.jpg

Your application can trigger the transactional campaign with:

{
    "event_identifier": "order-confirmed",
    "email": "john@example.com",
    "first_name": "John",
    "variables": {
        "name": "John Doe",
        "phone_number": "+1 555 123 4567",
        "order_id": "ORD-10452",
        "amount": "$249.00",
        "product_name": "Premium Subscription",
        "product_image": "https://example.com/images/premium-plan.jpg"
    }
}

The same campaign can then be used for another customer with completely different values.

Dynamic Email Templates

A transactional template should contain placeholders that correspond to the dynamic values supplied by your application.

For example, conceptually, an order confirmation email could contain:

Hello {{name}},

Thank you for your order.

Order: {{order_id}}
Product: {{product_name}}
Amount: {{amount}}
Phone: {{phone_number}}

An image can similarly use the supplied product image value:

{{product_image}}

The API accepts dynamic values through variables. The exact placeholder syntax supported by the email template renderer should match the variable-rendering implementation configured in your Rollout Email installation. The campaign configuration code confirms that variables are accepted and passed to the sending job, but it does not define the template placeholder syntax.

Using Different Types of Dynamic Data

You are not limited to customer information. You can pass application-specific data through the variables object.

Customer Information

{
    "name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+1 555 123 4567"
}

Order Information

{
    "order_id": "ORD-10452",
    "amount": "$249.00",
    "currency": "USD",
    "order_date": "September 12, 2026"
}

Product Information

{
    "product_name": "Premium Subscription",
    "product_image": "https://example.com/product.jpg",
    "product_url": "https://example.com/product"
}

Subscription Information

{
    "plan_name": "Basic Pro",
    "billing_period": "Monthly",
    "next_billing_date": "October 12, 2026"
}

Application-Specific Information

{
    "company_name": "Example Inc.",
    "account_id": "ACC-10245",
    "support_url": "https://example.com/support"
}

You can combine these values in a single variables object.

API Response

When the request is accepted, the API returns a successful response indicating that the transactional email has been queued for immediate delivery.

A successful request returns HTTP status:

202 Accepted

The response includes information such as:

• Campaign ID

• Event identifier

• Recipient email address

The API therefore confirms that the transactional email has been queued, rather than requiring the API request to wait for the email to finish sending.

Example Response

{
    "success": true,
    "message": "Transactional email queued for immediate delivery.",
    "data": {
        "campaign_id": 123,
        "event_identifier": "payment-success",
        "recipient": "customer@example.com"
    }
}

What Happens When the API Is Triggered

When Rollout Email receives a transactional request, it performs several checks before queueing the email:

1. Validates the request.

2. Finds the user's active transactional campaign matching the supplied event identifier.

3. Confirms that the campaign has an available email template.

4. Checks whether the recipient is suppressed.

5. Creates the contact if the email address is not already present.

6. Selects an active SMTP profile with available quota.

7. Places the email into the high-priority transactional sending queue.

The transactional email is then processed asynchronously rather than making the API request wait for the complete delivery process.

Suppressed Recipients

Rollout Email checks the suppression list before queueing a transactional email.

If the recipient has previously been suppressed because of a bounce or complaint, the request is rejected instead of sending another email to that address.

This helps prevent delivery attempts to suppressed recipients.

SMTP Availability

A transactional campaign must have an active and available SMTP profile assigned to it.

If no suitable SMTP profile is available, the API cannot queue the email for delivery.

Recommended Transactional Events

You can create separate transactional campaigns for different application events.

Each event identifier should be unique and should exactly match the value used by your application when calling the API.

Best Practices

Use Descriptive Event Identifiers

Prefer:

payment-success

over:

email1

Descriptive event names make integrations easier to maintain.

Keep One Purpose Per Campaign

Create separate campaigns for different transactional events.

For example:

payment-success
payment-failed
order-confirmed
password-reset

This allows each event to have its own template and configuration.

Pass Only the Data the Template Needs

If the template only requires:

name
order_id
amount

there is no need to send unrelated application data.

Keep Dynamic Data Consistent

Use consistent variable names across your integration.

For example, use:

product_name

rather than sometimes sending:

product

and sometimes:

item_name

Consistency makes templates and application integrations easier to maintain.

Transactional Email Checklist

Campaign Setup

• Create a new campaign.

• Select Transactional (Event-Driven API).

• Enter a unique API Event Name Hook.

• Select an email template.

• Set the campaign status to Active.

• Configure at least one SMTP Delivery Profile.

• Configure the required SMTP quota.

API Integration

• Authenticate the API request.

• Use the correct transactional API endpoint.

• Send the exact configured event_identifier.

• Provide the recipient email.

• Provide first_name when required.

• Pass dynamic information through variables.

• Ensure variable names match the template's supported placeholders.

Testing

• Trigger the event with a test recipient.

• Confirm that the API returns 202 Accepted.

• Confirm that the correct campaign is selected.

• Verify that dynamic values appear correctly.

• Check the campaign report for delivery and engagement.

• Review email events if delivery fails.