Send one-to-one emails — order confirmations, receipts, tickets, password resets — triggered by your own systems through the Apsis One API. This guide covers designing the email in Apsis One, creating the API key, building the API request, and following up on what was sent.
💡 What is a transactional email? A transactional email goes to one recipient as the result of something that person did — placed an order, bought a ticket, requested a new password. You design the email once in Apsis One, and your website, webshop or booking system then triggers it through the API, filling in the personal details (order number, product, date and so on) for each send.
🚨 Important for developers: use the section discriminator, not the section ID. The integration instructions shown in Apsis One display the API path with the section's numeric ID (for example /emails/sections/41259/...). The API call itself needs the section discriminator in that position (for example /emails/sections/com.apsis1.sections.user-created.default-abc123/...). Replace the number before you send the request.
On this page
1. Before you start
Setting up a transactional email is a shared job: you create and design the email in Apsis One, and a developer connects your system to the Apsis One API. Before you begin, make sure you have:
A section to create the email in. Many teams use a dedicated section for transactional sendings, so they're kept apart from marketing emails.
Access to create API keys in Apsis One (or someone who can create one for you).
A developer or integration partner who will make the API call from your system.
A list of the personal details each email needs — for an order confirmation that could be product name, order number and delivery date.
✅ Agree on the variable names with your developer before you design the email. The names you use in the editor are exactly the names the developer must send in the API request.
2. Create the transactional email
Go to Email in the left-hand menu and select Create email.
2a. Name and section
1. Enter a Working name (internal only), for example Transactional - Order confirmation.
2. In Send to profiles in this section, choose the section the email belongs to.
3. Open Advanced and tick Transactional Email.
4. Select Next.
💡 When you tick Transactional Email, the steps on the left change. A transactional email has five steps — Name, Templates, Design, Details, Overview — because there's no audience, A/B test or schedule to set. The API decides who receives it and when.
⚠️ The section can't be changed later. The email's content depends on the section's data, and the section is locked once you leave this step. This is also the section your developer will need the discriminator for.
2b. Choose a template
Pick a starting point from Pre-defined, Your templates or Themed, just as for any other email. Choosing Blank template works well if you want a clean, simple layout.
2c. Design the email and add variables
Build the email in the editor as usual. Wherever the content should be personal to each send, add a variable. Variables appear in the editor as tags, for example:
ToName— the recipient's nameProductName— what they orderedOrderNumberandTicketNumber— reference numbersValid— a date or validity period
⚠️ Remove unsubscribe and web version links. When you move on from the design, Apsis One checks for unsubscribe and web version links and shows a notice if it finds any: transactional emails shouldn't contain them. Select Make changes to remove them automatically, or Ignore to keep them.
✅ Keep images as links, not embedded files. Upload images to the Apsis One image gallery (or your own hosting) and link to them in the design.
2d. Email details
Fill in the Subject line, Pre-header text and the From details: sender Name, Email and Reply email. Then select Next.
💡 These are the default values. Your developer can override the subject, pre-header and sender details for an individual send in the API request, if needed.
2e. Overview and activation
The Overview step shows a summary of the email and an Integration instructions box. The box contains two things your developer needs:
The API path for this specific email —
/emails/sections/{section}/activities/{activity ID}/transactionsAn example request body, listing the variables you added in the design
Use the copy icon to copy the content and send it to your developer, then select Activate.
🚨 The path in the Integration instructions shows the section's numeric ID (here 41259). Tell your developer to replace it with the section discriminator. The activity ID in the path (the long ID after /activities/) stays as it is.
Once activated, the email is listed under Email → Transactional with the status Active, and is ready to be triggered through the API.
3. Create an API key for transactional emails
Your developer needs an API key that is allowed to send transactional emails.
1 Go to the API keys page in your account settings and create a new API key.
2 Give it a clear name, for example Transactional emails API.
3 Tick Allow sending transactional emails.
4 Select Create and share the credentials securely with your developer.
⚠️ The Allow sending transactional emails box is not ticked by default. Without it, the key can't trigger transactional emails, even if everything else is set up correctly.
4. Build the API request
This section is for the developer. Full technical details are in the Apsis One API documentation — Send a transactional email.
Each transactional email is sent with one POST request to:
{base URL}
/emails/sections/{section_discriminator}/activities/{activity_id}/transactions
Base URL — depends on your region (Europe or Asia). See the API documentation.
Authorization — a Bearer token generated from the API key created in step 3.
One request sends one email to one recipient.
4a. Use the section discriminator in the URL
Every section in Apsis One has both a numeric ID and a text discriminator. The Integration instructions show the ID, but the transactional endpoint expects the discriminator.
| Example |
❌ As shown in Integration instructions |
|
✅ What the API call needs |
|
Your developer can retrieve the section discriminator through the API (the sections endpoint returns each section's discriminator), or you can look it up for them in Apsis One.
🚨 A request that uses the numeric section ID will not send the email. If your developer reports that the request fails even though the email is Active and the API key has transactional sending allowed, check this first.
4b. The request body
Here's a complete example for the order confirmation email above:
{ "keyspace_discriminator": "com.apsis1.keyspaces.email", "profile_key": "jane.doe@example.com", "to_email_address": "jane.doe@example.com", "to_name": "Jane", "variables": { "ProductName": "Training jacket - reflective", "OrderNumber": "987654321", "TicketNumber": "123456789", "Valid": "1 October 2026" } }Field | Required | What it is |
| Yes | The keyspace of the profile the send is recorded on. See Choosing a keyspace. |
| Yes | The profile's key in that keyspace — for the email keyspace, the email address. |
| Yes | The address the email is sent to. |
| Yes | The recipient's display name. |
| When used in the design | The values for the variables in the email. Names must match the editor exactly. |
| No | Override the defaults set in the Details step for this send only. |
✅ Validate the JSON before sending. A missing comma or a misplaced bracket is the most common reason a first test fails.
4c. Choosing a keyspace
Every send creates events — Sent, Delivered, Open and so on — on the profile identified by keyspace_discriminator and profile_key. If no matching profile exists, Apsis One creates one automatically.
Keyspaces allowed | Use it when |
| The transactional events are posted on your existing profiles, so you can see them in the profile and use them in segments and automation. |
4d. Variables and attachments
Supported variable types: String, Number (integer) and Date.
Dates must be sent in ISO 8601 format, UTC (for example
2026-10-01T08:00:00Z).Keep variables short — they're meant to replace short pieces of text. All variables together, including their names, can be at most 200 kB.
Attachments can be added to the request. The total size of all attachments can be at most 2 MB.
Don't embed images in variables. Link to hosted images instead.
5. Follow up on sent transactional emails
In the email report
Go to Email → Transactional and open the email. The report shows Sent, Delivered, Opens, Clicks, Bounces and Spam Complaints, just like other email activities.
On the profile
Search for the recipient in Audience → Profiles (in the section the email belongs to), open the profile and go to Response data. Each send appears as Sent, Delivered and Open events. Select an event to see its details, including:
activityId— which transactional email was senttoEmailandtoName— who it was sent totransactionId— the unique ID of this specific send
💡 A profile created automatically by a transactional send only holds its unique identifier (for example the Email keyspace). Other attributes, like first name, stay empty unless you set them separately. The variable values you send are used in the email only — they aren't saved as profile attributes.
✅ Developers can also check the status of a send through the API using the Get a transactional email sending status endpoint. See the API documentation.
6. Troubleshooting
Symptom | Likely cause & fix |
The API request fails, although the email is Active. | Check that the URL uses the section discriminator, not the numeric section ID from the Integration instructions. |
The request is rejected as unauthorised. | Check that the API key has Allow sending transactional emails ticked, and that the token was generated from that key. |
The email arrives, but a variable is empty or shows the wrong value. | Variable names must match the editor exactly, including upper and lower case ( |
The request is rejected as invalid. | Validate the JSON — look for missing commas and misplaced brackets. Also check that dates use ISO 8601 (UTC) and that attachments are under 2 MB in total. |
The email can't be sent through the API. | Make sure the email was activated in the Overview step and shows as Active under Email → Transactional. |
I can't find the transactional events on the profile. | Search in the section the email was created in. Make sure to use the correct identifier (email or CRM ID) for best match. |
What's next?
Read more about API keys in Account settings.
Learn about unique identifiers and keyspaces in Audience.
Read the full Apsis One API documentation.
Need a hand? Open the in-platform chat or contact your Apsis support team.