Email Transactional

A transactional email is a kind of email that is triggered by a user action on an app. It is sent to facilitate an agreed-upon transaction between the sender and the recipient.

Various kinds of transactional email are:

  • Password resets
  • Shipping confirmations
  • Invoices and receipts
  • Account notifications
  • Social media updates
  • Welcome emails

These types of emails are generally sent programmatically through an API or SMTP relay.

Showing

  • This Taximail API endpoint allows you to get all the transactional list.
  • You are required to send GET request to /transactional API.
  • Taximail API will return an array of transactional groups.

GET https://api.taximail.com/v2/transactional

Parameter Type Description Required
session_id string The session_id from Authentication API. Yes

Example Request

GET v2/transactional?session_id=24bca90bac40b23e9fdcc8082299049d HTTP/1.1
Host: api.taximail.com

Example Result

{
  "status": "success",
  "code": 200,
  "data": {
            "transaction_group": [
                  {
                        "transactional_group_id": 217,
                        "transactional_group_name": "Default"
                  },
                  {
                        "transactional_group_id": 930,
                        "transactional_group_name": "Welcome"
                  },
                  {
                        "transactional_group_id": 1062,
                        "transactional_group_name": "eInvoice"
                  }
            ]
      }
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.transaction_group array Returns array of all transactional group.

Response Code

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id expired.

Sending

  • This API endpoint allows you to send email to a recipient.
  • You are required to send POST request and email content to /transactional API.
  • Taximail API will return the message_id to be used in message status.

POST https://api.taximail.com/v2/transactional

Parameter Type Description Required
session_id string The session_id from Authentication API. Yes
message_id string The message ID is a random identifier used for tracking statistics and should not be duplicated. It will be returned in the successful response.
transactional_group_name string Transactional's group name.

Default to Default group.
Yes
subject string The email's subject. Yes
to_name string The recipient's name. Yes
to_email string The recipient's email address. Yes
from_name string The sender's name. Yes
from_email string The sender's email address. Yes
reply_name string The reply's name.
reply_email string The reply's email address.
template_key string The template key need to use html content. Yes (If template_name and content_html is blank)
template_name string The template name need to use html content. Yes (If template_key and content_html is blank)
content_html string The content email in html form, in case use template key put custom field in json format here. Yes (If template_key and template_name is blank)
content_plain string The content email in text form.
report_type enum {False, 
Unique, Full}
The webhooks type report.
priority enum {0, 1} The priority level of email.
bcc string The BCC of email separate by comma.

Ex. "john@example.com,adam@example.com,josafh@example.com"
attachment string The json string of attachments specified with file name and file path.

Ex. "[{"filename":"contact1.pdf" ,"path":"https://example.com/contact1.pdf"}]"
cc array Array of cc specified with name and email addresses.

Ex. [{"name":"Albert Smith","email":"albert@example.com"} ,{"name":"Rose Smith","email":"rose@example.com"}]

Example Request

POST v2/transactional HTTP/1.1
Host: api.taximail.com

session_id=24bca90bac40b23e9fdcc8082299049d&message_id=mid_0000001&transactional_group_name=Welcome&subject=New+Member+Welcome&to_name=John+Smith&to_email=john%40example.com&from_name=Customer+Support&from_email=support%40example.com&reply_name=Customer+Support&reply_email=support%40example.com&template_key=16567a52906fb2a&content_html=&content_plain=&report_type=Full

Example Result

{
    "status": "success",
    "code": 202,
    "data": {
                "message_id": "mid_0000001",
                "claimed" : 1
          }
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.message_id string Returns the message_id use for tracking statistic.
data.claimed integer Returns the unit or credit used when sending an email.

Response Code

Code Result Description
202 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
Required field must not be blank.
File name in attachment not found.
Invalid email address format.
The number of existed subscribers exceed your plan limit.
You're not allowed to use this FROM address.
Link in html content must lower than 1000 character.
401 error Unauthorized or the session_id was expired.
403 error This email is in global suppression list.
Temporary skipping for inactive mailbox.
404 error The list not found.
Template key / Template name not found.
409 error Duplicate message ID.
Your recipients is over limit.
Can't sent multiple address with cc or bcc email.
Got invalid UTF-8 value serializing.
The attachment size exceeds the allowable limit.
Attachment file not found.
A SPF/DMARC policy record was found on this domain ({%domain%}). Our servers is not permitted to send emails which specified with this domain in the From email address.
503 error Not enough credit to send this campaign or email.
Connection error, please try again later.

Steps to send a transactional email

In this section, you will learn how to send a transactional email via the Taximail API. Usually, it requires a developer should set up a system that will send templates to specific recipients. In Taximail, you can quickly create transactional emails like you would any email. You can send these emails to almost all contacts in your audience.

Our Integrations section helps you to kickstart the procedure for sending transactional email.

Taximail offers two ways to send the transactional email:

  • via the API( which is essentially an API call)
  • via SMTP relay( which is an SMTP connect).

For a free subscription, we provide only the API call mode.

For paid subscription, we provide both the mode's - API as well as SMTP relay.

The following steps will help you get started:

  1. Go to the Integrations section on the main menu of Taximail app.

  2. Look for the SMTP relay section, select it and open it.

Import file

  1. Under SMTP Relay configuration section, three params need to be defined.

    SMTP Relay server - This is similar to an email server like gmail.

    Password - This is similar to login credential like gmail password.

    Username - This is similar to login credentials like gmail username.

The following code segment is an example of inserting params in the SMTP server configuration.

$smtp_server['host'] = "smtp-dev.taximail.com";
$smtp_server['username'] = "sm170001";
$smtp_server['password'] = "ftLgAgfdrErtr";

Similarly, in the app, it will be displayed as follows:

Import file

  1. For both modes, we use the following two ways:
  • By Template key
  • By custom HTML content

There’s an added layer of value to sending through Taximail's SMTP Relay. Before our SMTP servers send an email, our system automatically adds link trackers in the body of your message. This then allows you, as the user, to properly track opens and clicks after an email has been received.

  1. By template key method, you need to insert the parameter for the template key in the API.

$mail->addCustomHeader("X-TAXIMAIL-TEMPLATE-KEY: 13095cf8c3137fea8");

In APP, it will be displayed as follows:

Import file

To specify the template key as a parameter, it should be defined in the Transaction API endpoint.

An example is shown below:

POST v2/transactional HTTP/1.1
Host: api.taximail.com

session_id=24bca90bac40b23e9fdcc8082299049d&message_id=mid_0000001&transactional_group_name=Welcome&subject=New+Member+Welcome&to_name=John+Smith&to_email=john%40example.com&from_name=Customer+Support&from_email=support%40example.com&reply_name=Customer+Support&reply_email=support%40example.com&template_key=16567a52906fb2a&content_html=&content_plain=&report_type=Full
  1. Template key parameter is inserted as a JSON string to the body of the HTML section.

  2. The email content will be inserted to JSON data as follows:

    $json_data = '{"CF_HTMLContent":"some html content"}';

In the SMTP method, a variable like 'Hello username' is passed as a custom field in the template.

     For example:  $arr = [
                      "CF_Firstname" => 'Firstname'
                     ];
  1. By HTML method, the email content will be passed as an HTML string in the body parameter.

  2. The following code example shows an example of how HTML content is inserted in the body parameter.

    $body = '{"CF_HTMLContent":"some html content"}';

You can classify your transactional email by grouping, sending with saved template email, and etc.

Hopefully, this guide helped you to understand how transactional emails work.

Now, it’s your chance to start using transactional emails to get the possible value and continue building positive customer relationships.

Message status

  • This Taximail API endpoint allows you to get the status of delivered transactional email to the recipient.
  • You are required to send GET request to transactional/{message_id} API.
  • Taximail API will return message status object such as email, ready time, sent time, open time and other.

GET https://api.taximail.com/v2/transactional/{message_id}

Parameter Type Description Required
session_id string The session_id from Authentication API. Yes

Example Request

GET v2/transactional/mid_0000001?session_id=24bca90bac40b23e9fdcc8082299049d HTTP/1.1
Host: api.taximail.com

Example Result

{
    "status": "success",
    "code": 200,
    "data": {
                "email": "john@example.com",
                "ready": "2016-01-07 10:13:15",
                "sent": "2016-01-07 10:13:19",
                "open": [
                      "2016-01-07 10:14:03"
                ],
                "open_count": 1,
                "click": [],
                "click_count": 0
       }
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.email string Returns recipient's email.
data.ready string Returns datetime ready to send email.
data.send string Returns datetime to send email.
data.open string Returns datetime recipient open the email.
data.open_count string Returns summary open email count.
data.click string Returns datetime recipient click the email.
data.click_count string Returns summary click email count.

Response Code

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id expired.
404 error The message id not found.
Title
Title SEO [Optional]
Description SEO [Optional]
Friendly URL [Optional]
IFRAME Content [Optional]
Priority
Markdown
We use cookies
This website uses cookies to enhance your browsing experience on our website, to show you personalized content and targeted ads, to analyze our website traffic, and to understand where our visitors are coming from. You can manage your preferences by clicking Change Preferences. Learn more about this on Cookie policy
Change Preferences
Accept All