Sending transactional email through the API

This guide explains how a transactional message is sent to Tarvent: how your app authenticates, what a transaction request contains, the options you can set, and how to test safely. It stays at a conceptual level. To generate real, ready-to-run code, use the built-in Email API Call Builder, described below.

In this guide, you'll find:

The Email API Call Builder
Authentication
What a transaction contains
Sending options
Testing with sandbox
Understanding the response
FAQs

1 The Email API Call Builder

The fastest way to get started is the Email API Call Builder, found in the Help menu. It lets you set every option for a message through the UI, then generates working code you can paste into your app. Code is available for C#, Node.js, Python, PHP, Go, and Java, plus an SMTP relay example.

The builder also includes a full reference of every field, the response format, and the possible error codes, so it doubles as your API documentation while you build.

2 Authentication

Transactional messages are sent to Tarvent's API. Two things identify your request:

Your API key, sent in the X-API-KEY header. Create one in your account settings and keep it secret.
Your account ID, sent in the Account header.

You can also relay messages through Tarvent's SMTP address if that suits your stack better. The Call Builder generates an SMTP example alongside the code samples.

3 What a transaction contains

A single message is called a transaction. At minimum it needs a sender, at least one recipient, a subject, and content. The main parts are:

Sender — the "from" name and address (required). The from address must use a domain you've verified in Tarvent. You can also set a reply-to address.
Recipients — one or more recipients, each marked as To, CC, or BCC. You can address a recipient by email, or reference an existing Tarvent contact by its ID (which lets Tarvent use that contact's data).
Subject — the subject line (required).
Content — either a saved template (by ID) or content you include directly in the request as HTML and plain text. If you supply a template, it takes priority.
Personalization — variables (merge data) that get inserted into your content by name. You can set them for the whole message or per recipient; a per-recipient value overrides a message-level one of the same name.
Reporting labels — an optional group name and tags to organize messages in your reports (for example, "order confirmations"). Metadata can also be attached for reference in reporting.

Note: Attachments aren't supported on transactional messages. The "group name" is a reporting label, not a contact group.

4 Sending options

Beyond the message itself, a transaction supports a range of options:

Tracking — turn open tracking, click tracking, and reply tracking on or off. Note that when reply tracking is on, it manages replies for you and your reply-to address is ignored.
Site tracking — when you reference a contact (rather than a bare email), you can enable tracking of that contact's activity on your site.
Scheduling — send immediately, or set a future send time (UTC).
Show recipients — choose whether recipients can see each other (BCC recipients are always hidden).
Suppression — normally suppressed addresses are skipped; you can optionally override this for a specific message.
Auto-generate content — automatically create a plain-text version from your HTML (or vice versa).
Analytics — append UTM parameters to your links for your web analytics.
Language — a culture code that controls how numbers, dates, and currency are formatted in the message.

5 Testing with sandbox

Before you send anything real, you can test your integration with sandbox mode, shown in the Call Builder as Force error response. When it's on, the API validates your request and returns an error response you choose (a general error or an invalid-email error) without delivering any mail. It's the easiest way to confirm your app handles errors correctly. Sandbox requests are limited to 10 recipients.

6 Understanding the response

The API responds with a result for each recipient, including a transaction ID (one per recipient), a request ID (shared across the request), the recipient's email, and an error code and message (a code of 0 means success). The response also returns your current credit information, such as how many credits remain in the period, so your app can watch its usage.

7 FAQs

Where do I get the code to send a message?

Use the Email API Call Builder in the Help menu. Configure the message in the UI, then copy the generated code for your language (C#, Node.js, Python, PHP, Go, Java, or SMTP) into your app and replace the placeholder with your real API key.

How do recipients, CC, and BCC work?

Every recipient is listed together, and each one is marked as To, CC, or BCC. At least one To recipient is required. Each recipient counts as a credit.

Can I send without my message being delivered, just to test?

Yes. Turn on "Force error response" (sandbox) in the Call Builder. The API validates your request and returns the error you selected without delivering any email. Sandbox requests are capped at 10 recipients.

Why was my message rejected?

Common reasons are a missing required field (from address, subject, or a To recipient), a from address on a domain you haven't verified, or being out of credits. The API returns an error code and message for each; the Call Builder lists the full set of codes.