Overview

Basic Email Parsing

Basic email parsing is available with every Traxo Developer Account.

Emails can be submitted via forwarding to the developer mailbox associated with each Traxo Platform Application or via the Traxo API.

Typical processing takes place within a few seconds. The resulting data is delivered to the Webhooks URL associated with the application or can be requested directly from the API.

Integrated Email Parsing

Integrated Email Parsing builds on the basic service by additionally injecting the resulting travel data into the core Traxo experience.

When an incoming email for an existing Traxo member is detected, the parsed segment data is automatically added to the member's account.

If an incoming email cannot be matched to an existing Traxo member, the sender will receive a welcome email from Traxo indicating how to join.

To upgrade to Integrated Email Parsing, contact support.

Folio Email Parsing New

In addition to parsing travel booking emails, Traxo supports parsing of hotel folios as part of the basic email parsing service.

Folios are the receipts that travelers receive from the property that detail all of their purchases during their stay - the true total cost of a hotel.

Traxo’s Folio email parsing service supports folio documents originally sent from the hotel in HTML and text-based PDF format. Travelers should be directed to request these emails from their hotel if they are not already sent the document.

Learn more about the folio response format below.

Pricing

Prices and free-tier availability subject to change.

Free-tier

The free tier provides 100 free parses per rolling 24-hour period.

Manual processing is disabled by default for clients operating within the free-tier. Contact support to have manual proessing enabled for your application(s).

Attribution is required to be clearly shown to the end-user near the presentation of the parsed data. Attribution must be, at a minimum, a textual "Powered by Traxo" hyperlink that directs the user-agent to https://www.traxo.com.

If the end-user will not be directly interacting with the parsed data, the minimum attribution should be placed within the application or website in a location visible to the end-user.

Commercial Terms

Please contact sales for current commercial terms.

Setup

1. Developer Account

Create a Traxo Developer Account or ensure that you are logged in to the developer portal. A new application will be created within each new developer account.

2. Developer Mailbox

Visit the Apps page and select "View" for an application within your account. Locate your Developer Mailbox.

This is the private mailbox for the currently selected application. It can be used directly by forwarding travel emails from your mail client or mail server.

Note that it may take up to a minute after an application is first created for the developer mailbox to be populated.

3. Vanity Mailbox

Most developers will choose to publish a vanity mailbox (i.e. trips@example.com) on their own domain for use by their end-users.

Emails should be forwarded via server-side forwarding from the vanity mailbox to the private developer mailbox for the application.

4. Webhooks

From the Apps detail page, ensure that a Webhooks URL is properly set if you intend to receive real-time events regarding email processing status.

Learn more about using webhooks with Traxo from the Webhooks documentation.

To quickly setup a webhooks receiver for testing, Traxo recommends RequestBin. RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way for up to 24 hours.

Processing

Email parsing is always an asynchronous process.

If a valid Webhooks URL is registered, that url will begin receiving events (via HTTP POST) as soon as an email is received by Traxo.

Automated parsing is first attempted on the email contents. If successful, basic email parsing results will be available within approximately 5 seconds.

If automated parsing is unsuccessful or incomplete and the mailbox has manual processing enabled, the email will be flagged for manual review.

Manual review is a best-effort process typically completing within 30-60 minutes of original receipt.

Developers utilizing the Integrated Email Parsing service can typically expect to see updates applied to existing member accounts within 30-60 seconds of original receipt. Note that there may be no itinerary changes applied to an existing member account if the trip building process determines that no changes are required based on the received data.

Email Statuses

Emails progress through various statuses following initial submittal until reaching a final state.

The table below lists the common statuses that may be encountered. Status values not listed here should be considered temporary or transient.

Status Description Final State
Processing The message is being processed
For-Review The message has been flagged for manual review
In-Review The message has entered manual review
Processed The message was processed successfully Yes
Failed The message could not be processed Yes
Invalid There was no travel data within the message Yes

User Address

The "user address" is a key attribute when utilizing the Integrated Email Parsing service.

This address is used for all downstream processing and should be the address of the end-user.

If a Traxo member account can be matched to this address, the data from the email will be integrated into that specific member account.

If a Traxo member account cannot be matched to this address, the address holder will receive the welcome email notification with instructions on how to create an account.

This address is set by default to the "From" address identified in the email headers.

If the parsing algorithms determine that a more applicable address for the end-user is present in the email body, the body value will be used.

The address value used may be customized by contacting api-support@traxo.com and requesting the To, From, or Body address for a specific client_id.

API Operations - Emails

Traxo email parsing services may be utilized entirely via API, server-side email forwarding, or a combination.

Visit the API Explorer for email and mailbox operations to see the available operations, examples, and live data.

The original contents of a message are available via API call.

API Operations - Mailboxes

This collection of endpoints provides operations required to create and manage private mailboxes used in email parsing.

Visit the API Explorer for email and mailbox operations to see the available operations, examples, and live data.

Response Format - Segments

The email response contains a collection of zero or more "segment" objects. Segments may be identified by their type parameter (one of: air, car, hotel, rail, cruise, activity).

Each type of segment object in an email response is modeled very similarly to the segment objects returned by the Traxo API for trip or segment endpoints.

This similarity in response format should allow developers to write a standard interpreter for each type of segment, that can, with a few modifications, be used for segments returned via email response or the Traxo API.

Common Attributes

Status

The status of each parsed segment can be used to determine whether the content of the email represented a "booking" or a "cancellation".

Status Description
Active The segment is active and is upcoming.
Past Date The segment is active and in the past.
Deleted The segment has been cancelled.

Air

{
    "airline": "Alaska Airlines, Inc.",
    "arrival_datetime": "2015-06-14T19:39:00",
    "arrival_time_zone_id": "America/Los_Angeles",
    "class_of_service": "Coach",
    "confirmation_no": "ABC123",
    "created": "2015-04-10T06:03:07+0000",
    "currency": "USD",
    "departure_datetime": "2015-06-14T17:40:00",
    "departure_time_zone_id": "America/Chicago",
    "destination": "PDX",
    "destination_name": "Portland International",
    "destination_admin_code": "OR",
    "destination_city_name": "Portland",
    "destination_country": "US",
    "destination_lat": "45.5833320617676",
    "destination_lon": "-122.599998474121",
    "fare_basis_code": "G",
    "first_name": "Roger",
    "flight_number": "655",
    "iata_code": "AS",
    "last_name": "Sterling",
    "normalized_airline": "ASA",
    "number_of_pax": "1",
    "origin": "DFW",
    "origin_name": "Dallas/Fort Worth International",
    "origin_admin_code": "TX",
    "origin_city_name": "Dallas",
    "origin_country": "US",
    "origin_lat": "32.9000015258789",
    "origin_lon": "-97.0500030517578",
    "price": "380.20",
    "seat_assignment": "22D",
    "source": "Alaskaairlines",
    "status": "Active",
    "ticket_number": "1234567890",
    "type": "Air",
    "travelers": [
      {
        "name": "Roger Sterling",
        "first_name": "Roger",
        "last_name": "Sterling"
      }
    ],
    "tickets": [
      "1234567890"
    ],
    "seats": [
      "22D"
    ],
    "price_details": [
      {
        "type": "total",
        "name": "Total",
        "value": "380.20",
        "units": "USD"
      }
   ]
},

Car

{
    "car_company": "Hertz",
    "car_description": null,
    "car_type": "Intermediate 2 or 4 dr., ICAR (C",
    "confirmation_no": "G0000000000",
    "created": "2015-04-10T06:06:35+0000",
    "currency": "USD",
    "dropoff_address1": "3500 South Las Vegas Boulevard",
    "dropoff_address2": null,
    "dropoff_admin_code": "NV",
    "dropoff_city_name": "Las Vegas",
    "dropoff_country": "US",
    "dropoff_datetime": "2015-07-10T12:00:00",
    "dropoff_lat": "36.1749687194824",
    "dropoff_lon": "-115.137222290039",
    "dropoff_postal_code": "89109",
    "dropoff_time_zone_id": "America/Los_Angeles",
    "first_name": "Pete",
    "hours_of_operation": "Mon-Sun 7:00am-1:00pm 2:00pm-5:00pm",
    "last_name": "Campbell",
    "normalized_car_company": "ZE",
    "pickup_address1": "3500 South Las Vegas Boulevard",
    "pickup_address2": null,
    "pickup_admin_code": "NV",
    "pickup_city_name": "Las Vegas",
    "pickup_country": "US",
    "pickup_datetime": "2015-07-09T12:00:00",
    "pickup_lat": "36.1749687194824",
    "pickup_lon": "-115.137222290039",
    "pickup_postal_code": "89109",
    "pickup_time_zone_id": "America/Los_Angeles",
    "price": "60.59",
    "source": "Hertz",
    "status": "Active",
    "type": "Car",
	"travelers": [
      {
          "name": "Pete Campbell",
          "first_name": "Pete",
          "last_name": "Campbell"
      }
    ],
    "price_details": [
      {
          "type": "total",
          "name": "Total",
          "value": "60.59",
          "units": "USD"
      },
      {
          "type": "tax",
          "name": "Tax",
          "value": "9.63",
          "units": "USD"
      }
    ]
}

Hotel

{
    "address1": "1895 Sidewinder Drive",
    "address2": null,
    "admin_code": "UT",
    "cancellation_policy": "\u2022 Please note that a change in the length or dates of your reservation may result in a rate change. \u2022 To ensure that you receive this special rate, we will charge your credit card a prepayment of 1,282.58 USD. \u2022 Please send a check or money order prepayment to PARK CITY MARRIOTT PO BOX 684447 ATTN: RESERVATIONS PARK CITY UT 84060 US \u2022 You may cancel your reservation for no charge until Tuesday, January 20, 2015 (45 day[s] before arrival). \u2022 Please note that we will assess a fee of 641.29 USD if you must cancel after this deadline. If you have made a prepayment, we will retain all or part of your prepayment. If not, we will charge your credit card. \u2022 Travel agents: please note that this rate is commissionable. RATE GUARANTEE LIMITATION(S) \u2022 Changes in taxes or fees implemented after booking will affect the total room price. \u2022 Please note that a change in the length or dates of your reservation may result in a rate change. ADDITIONAL INFORMATION \u2022 The Responsible Tourist and Traveler A practical guide to help you make your trip an enriching experience",
    "checkin_date": "2015-03-06",
    "checkout_date": "2015-03-10",
    "city_name": "Park City",
    "confirmation_no": "12345678",
    "country": "US",
    "created": "2015-04-10T04:49:35+0000",
    "currency": "USD",
    "first_name": "Don",
    "hotel_name": "Park City Marriott",
    "last_name": "Draper",
    "lat": "40.6460609436035",
    "lon": "-111.497970581055",
    "number_of_rooms": "1",
    "postal_code": "84060",
    "price": "1282.58",
    "rate_description": null,
    "room_description": null,
    "room_type": null,
    "source": "Marriott",
    "status": "Active",
    "time_zone_id": "America/Denver",
    "type": "Hotel",
    "travelers": [
      {
        "name": "Mr. Don Draper",
        "first_name": "Don",
        "last_name": "Draper"
      }
    ],
    "price_details": [
      {
        "type": "total",
        "name": "Total",
        "value": "1282.58",
        "units": "USD"
      },
      {
        "type": "tax",
        "name": "Tax",
        "value": "31.64",
        "units": "USD"
      }
    ]
}

Rail

{
    "rail_line": "Amtrak",
    "arrival_datetime": "2015-06-14T19:39:00",
    "arrival_time_zone_id": "America/Los_Angeles",
    "confirmation_no": "ABC123",
    "created": "2015-04-10T06:03:07+0000",
    "currency": "USD",
    "departure_datetime": "2015-06-14T17:40:00",
    "departure_time_zone_id": "America/Chicago",
    "destination": "PDX",
    "destination_name": null,
    "destination_admin_code": "OR",
    "destination_city_name": "Portland",
    "destination_country": "US",
    "destination_lat": "45.5833320617676",
    "destination_lon": "-122.599998474121",
    "first_name": "Roger",
    "last_name": "Sterling",
    "number_of_pax": "1",
    "origin": "DAL",
    "origin_name": null,
    "origin_admin_code": "TX",
    "origin_city_name": "Dallas",
    "origin_country": "US",
    "origin_lat": "32.9000015258789",
    "origin_lon": "-97.0500030517578",
    "price": "380.20",
    "seat_assignment": "22D",
    "source": "Amtrak",
    "status": "Active",
    "ticket_number": "1234567890",
    "type": "Rail",
    "train_number": "1234",
    "travelers": [
      {
        "name": "Roger Sterling",
        "first_name": "Roger",
        "last_name": "Sterling"
      }
    ],
    "tickets": [
      "1234567890"
    ],
    "seats": [
      "22D"
    ],
    "price_details": [
      {
        "type": "total",
        "name": "Total",
        "value": "380.20",
        "units": "USD"
      }
   ]
}

Activity

This segment type is used for events, meetings, etc.

{
    "activity_type": "General",
    "activity_name": "Van Halen",
    "first_name": "Don",
    "last_name": "Draper",
    "start_name": "Park City Ampitheater",
    "start_admin_code": "UT",
    "start_address1": "1895 Sidewinder Drive",
    "start_address2": null,
    "start_city_name": "Park City",
    "start_country": "US",
    "start_lat": "40.6460609436035",
    "start_lon": "-111.497970581055",
    "start_postal_code": "84060",
    "end_name": "Park City Ampitheater",
    "end_admin_code": "UT",
    "end_address1": "1895 Sidewinder Drive",
    "end_address2": null,
    "end_city_name": "Park City",
    "end_country": "US",
    "end_lat": "40.6460609436035",
    "end_lon": "-111.497970581055",
    "end_postal_code": "84060",
    "start_datetime": "2015-03-06 18:00:00",
    "end_datetime": "2015-03-10 22:00:00",
    "confirmation_no": "12345678",
    "created": "2015-04-10T04:49:35+0000",
    "currency": "USD",
    "price": "1282.58",
    "source": "Email",
    "status": "Active",
    "time_zone_id": "America/Denver",
    "type": "Activity",
    "travelers": [
      {
        "name": "Mr. Don Draper",
        "first_name": "Don",
        "last_name": "Draper"
      }
    ],
    "price_details": [
      {
        "type": "total",
        "name": "Total",
        "value": "50.00",
        "units": "USD"
      },
      {
        "type": "tax",
        "name": "Tax",
        "value": "8.25",
        "units": "USD"
      }
    ]
}

Extended Fields

Extended fields provide data elements specific to email parsing and are delivered with each segment when available and as shown in the examples.

These optional fields are used when data elements do not fit into the standard model for a given segment type.

Extended fields are currently only provided via automated email parsing. Support for these fields via manual parsing may be added in a future release.

price_details

A collection of price details (line items) from the email.

type The normalized type of line item. One of: total, tax, fee

name The free-form name of the item.

value The value of the line item as a numeric string.

units The currency code or other suitable unit definition.

travelers

A collection of traveler attributes.

name The name string directly from the email.

first_name The first name and middle name or initial (if present).

last_name The last name and suffix (if present).

tickets

A collection of ticket numbers. Typically available with air and rail segments.

seats

A collection of seats. Typically available with air and rail segments.

Integration Notes:

Response Format - Folio

Submitting folio emails is the same as travel bookings. There is no need to create more mailboxes as the same mailbox can be used both types of documents.

The parsed data is delivered using the same methods as travel bookings - webhook and direct API request. Refer to the Email Parsing API Explorer for instructions and additional parameters to request folio receipt content.

Folio receipt items include the following parameters:

type One of the folio receipt types listed in the table below.

name The name of the line item.

value The amount of the line item. Always a positive value.

units The currency code of the line item.

desc An additional description of the line item.

date The ISO8601 date of the line item.

Receipt Types

Traxo assigns each line item of a folio receipt a single ‘type’ value from the following list:

fee tax payment business-center
room-charge event meal meal-breakfast
meal-lunch meal-dinner mini-bar gratuity
laundry parking ground gift
cash-advance entertainment vat telecom
fuel

Example

This example shows a typical hotel folio response when requested via the API.

This response includes a collection of zero or more segments and a collection of "receipt" items.

Request:

GET /v2/emails/:id?include=results

Response:

{
    ....

    “includes”: {
        “segments”: [
            {
                "address1": "1895 Sidewinder Drive",
                "address2": null,
                "admin_code": "UT",

                ....

            }
        ],
        “receipt”: [
            {
                 "type": "fee",
                 "name": "Rm Chg STDO T1 Transient",
                 "value": 125.1,
                 "units": "USD",
                 "desc": "J1337",
                 "date": "2016-07-18T00:00:00"
            },
            {
                 "type": "tax",
                 "name": "State Occupancy Tax",
                 "value": 7.51,
                 "units": "USD",
                 "desc": "T2337",
                 "date": "2016-07-18T00:00:00"
            }
        ]
    }
}

Working with Errors

HTTP 403

{
"code": 403,
"error": "client_access_denied",
"error_description": "Client not authorized for email parsing"
}

If this error is encountered, please contact api-support@traxo.com.

Webhooks

The webhooks handler should listen for the "email.created" and "email.updated" events.

Other (non-email) event types may be received. See the Webhooks documentation for more details.

Example

{
    "created": "2015-04-10T04:49:34+00:00",
    "data": {
        "object": {
            "created": "2015-04-10T04:49:21+0000",
            "from_address": "testuser@example.com",
            "id": "405612237952923800",
            "mailbox_id": "405621341795997700",
            "modified": "2015-04-10T04:49:34+0000",
            "segments": [
                {
                   .... truncated ....
                }
            ],
            "source": "Email",
            "status": "Processed",
            "subject": "Fwd: Reservation Confirmation #12345678 for Park City Marriott",
            "to_address": "plans@example-travelapp.com",
            "user_address": "testuser@example.com"
        }
    },
    "type": "email.updated"
}

Implementation Notes