AwardWallet Email Parsing API

Introduction

Email Parsing API allows you to extract structured information from an unstructured email. Specifically, you can extract travel itineraries from virtually any travel provider using this REST API. The email parser API can automatically process incoming emails, it will extract data from incoming emails and using webhook integrations send the resulting structured data to your endpoint. The main benefit of this email scraping technology is that you can import travel reservations that belong to your users regardless of how these reservations were booked.

Technically here is what happens under the hood: when an email is received for parsing it gets put into a queue for processing, email workers grab emails out of that queue and send them for parsing. The actual process of parsing consists of applying tens of thousands of regular expressions against a given email until the right parser is found and the required data attributes are extracted from that email. Some of our clients have asked us: "What is the difference between email parsing and email scraping?" and the answer is: there is no difference, email scraping (or parsing), just like web scraping means retrieving structured format from unstructured text, be that a web page or body of an email. There are usually two ways to do that: (1) to run regular expressions against that body of text or (2) run XPath queries if the text body has proper HTML formatting.

With AwardWallet Email Parsing API you can send any travel itinerary or reservation to our endpoint and the parse API will extract the data and return the reservation data in a structured format (JSON) for your consumption. Parsing is done automatically and takes just a few seconds.

If you have an email reservation and want to do a quick test you can upload the .eml file or copy-paste the raw content of the email via our example test page. You should see the parsing results immediately after submitting the request at the bottom of the page.

For production mode, the API is designed to work asynchronously. Here is the workflow diagram explaining what happens to an email once it is received by the API:

At a high level, here is how the API works:

You submit an email message for parsing, and specify your callbackUrl (must be registered with us prior to using the API) in your request. Our API will respond with a queued status. At this point you don’t know if your message was parsed or not.

Your message will be processed by an automated parser. Shortly, typically within seconds, you will receive a response to your callbackUrl, with one of the status codes (which are described below). In most cases, you should get a success code and the results of the parsing will be returned to you in that callback response. For testing, instead of receiving the results to your callback URL, you may simply call the /getResults/{requestID} method to see the results.

If you get a review status - you should expect a subsequent callback with either success, invalid, restricted or skipped status. At this point we are not able to guarantee any time range for manual review process.

Typically, the emails that you send to us are stored on the AwardWallet’s servers for two weeks (in the Amazon AWS cloud). After that, the emails are permanently deleted from our servers. If it so happens that there will be emails in the review status at the two-week mark we will also send you a response to your callbackUrl with a status of timeout at the time when we purge the emails.

Every method that we make available as part of this API can be invoked through two endpoints, the ones that have the -eu in the URL point to our EU infrastructure, where all the data processing happens inside EU. The other one points to the servers hosted in the US.

Authentication

To authorize, use this code:

# TODO: With php. Build php example

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "X-Authentication: userapikey"

Every API call needs to be authenticated with an API authntiction token. This token is passed in the "X-Authentication" field with the https request header. The token is formed by concatinating the API username and API password with a ":" symbol. You need to contact us to get your API credentials.

X-Authentication: YourUserName:YourPassword

Obviously you need to replace YourUserName:YourPassword with your personal credentials.

/parseEmail is going to be your main method that you are going to be calling to work with this API. This is where you will be sending your emails with travel reservations.

HTTP Request

POST https://service.awardwallet.com/email/json/v2/parseEmail

POST https://email-eu.awardwallet.com/email/json/v2/parseEmail

Query Parameters

Parameter

Type

Required

Description

email

string

true

Full email source, including MIME headers and MIME body

callbackUrl

string

false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with us. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

returnEmail

string

true

Indicates whether we should include the original email source in the response or not. There are three possible values:

headers - include only the headers of the email

all - include the entire email

none - do not include the email in the response

userData

string

false

Any text. We will return this text in the response field untouched. You can send your internal message id, or any other data. It can also be used for troubleshooting with our support team as you can reference that value so that we can easily identify the email you are inquiring about.

Response

Parameter

Type

Required

Description

apiVersion

int

true

The version of the API being used

status

string

true

The status of the request. Can have one of two values:

queued - the email has been placed into the AwardWallet’s queue, as soon as it is processed the results will be available and will be sent to your callback URL.

error - the email has not been placed into the AwardWallet’s queue, see the errorMessage field for more details.

errorMessage

string

false

If you get an error in the status attribute the actual error message will be available in this field.

requestIds

array

true

Collection of request IDs, which can be used to retrieve the parsing results using the /getResults/{requestID} method and also these request IDs will be sent with the response to your callback URL. Multiple request IDs could be returned if the submitted email contained one or more nested (attached) emails. Each ID can be used separately to retrieve the parsing results of each of these emails.

Whenever you are testing or troubleshooting our API it may be inconvenient to work with a callbackurl to analyze the results. For this reason, you can simply call this method to get the parsing results for any given email that you sent to us in the last two weeks.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/getResults/{requestId}

GET https://email-eu.awardwallet.com/email/json/v2/getResults/{requestId}

queued - The email is sitting in the queue, waiting to be processed by the parser you can call this method again in a few seconds or you can wait to receive the results to the callbackUrl that you specified.

invalid - It was determined that this email does not contain a valid travel itinerary or reservation. See the statusMessage for more details.

review - The automated parsers failed to parse this email, at this point the message is going to be placed into the manual queue for someone at AwardWallet to check it and decide if we should adjust a parser and re-run it again through the parsing process. You should not expect successful parsing results quickly (in under 1 hour) as someone manually has to review the email and adjust the parsers.

restricted - This is a restricted provider that AwardWallet is not allowed to parse at this point.

skipped - This email was reviewed and we determined that this is an itinerary and for one reason or another we did not parse this reservation. This email was not counted against your license count.

timeout - We were not able to review this email in a timely fashion, thus we don’t know if this is a valid reservation or not. This email was purged from our queue automatically and was not counted against your license count.

statusMessage

string

false

If you get invalid as the returned value in the status field, this field will have additional information for you.

rejectMethod

string

false

This field indicates the reason why our system determined that an email does not contain a valid travel reservation in it. The possible values are:

auto - The system automatically (using built-in filters) determined that the email does not contain a valid itinerary.

manual - This email was reviewed by our support staff and it was determined that it does not contain a valid travel reservation.

incomplete - This email might contain a travel reservation, but some required fields are missing from it.

missingFields

array

false

If the rejectMethod field returns the incomplete value, this field will return an array of names of missing fields. For example if segments.arrival.airportCode is a required field and is missing in the email, this value will be returned here, so you know exactly why this email failed to parse.

providerCode

string

false

Alpha-numeric value with no spaces that uniquely identifies any given provider within the AwardWallet interface.

fromProvider

boolean

false

Indicates if this email was sent directly by the provider as opposed to the user forwarding that message.

If the email contains loyalty information (i.e. account balance, account number, elite status, etc.) like a monthly statement, then we will return all that loyalty information in this object. We typically do this for United, Delta and Southwest statements.

Some email headers and other metadata will be returned in this object. If you need to get the full headers, please set the returnEmail attribute to headers and you will get them via the email attribute.

Same as the metadata attribute above, except nestedEmailMetadata is present only when the metadata.nested attribute is set to true. It means that this email was received as an attachment to another email that was submitted to us. In that case, the metadata field will contain the headers of the parent email (the one that was actually submitted to the API) and this nestedEmailMetadata field will contain the headers of the nested email, which parsing results are actually presented in this response.

An array of email recipients listed in the Cc: field of the email (if any).

subject

string

false

Email subject.

receivedDateTime

string

false

Date and time when the email was received in the mailbox in the YYYY-MM-DDThh:mm:ss format. The time will be in UTC+0 time zone.

nested

boolean

false

Set to ‘true’ if this email was received as an attachment to another email, that was actually submitted, and ‘false’ otherwise.

userEmail

string

false

Presumable email address of the actual end user. This email address may be parsed from the email headers (from, to, cc) or from the email body.

mailboxId

integer

false

Filled in with mailbox id, if this message was downloaded from mailbox added with /mailboxes/ api

Email Address

Parameter

Type

Required

Description

name

string

false

The name that is associated with the email address.

email

string

true

The actual email address.

Loyalty Information

If the email contains loyalty information (i.e. account balance, account number, elite status, etc.) like a monthly statement, then we will return all that loyalty information in this object. We typically do this for United, Delta and Southwest statements.

Parameter

Type

Required

Description

balance

double

false

Loyalty account balance, i.e. how many miles or points the user has.

balanceDate

string

false

In some cases, the statement email may have a balance date (basically stating that this was the balance as of some specific date). If we see such a date it will be returned in this field.

Email may contain account transaction history. If that is the case the actual account transactions will be returned in this array. Please note that we only support specific formats for specific providers, if you wish to use this feature you would need to contact our support team to better understand which email formats are supported.

History Row

Unfortunately, most providers present their history differently, as much as we want to unify this information it doesn’t seem to be possible, so when presenting a single history row, we define each field separately with three values as described below.

History Field

Think of a single row of data that describes a historical transaction. fields are the individual values that comprise that transaction. Instead of just providing you with a text value we provide you with an array of metadata that define what this value is.

Parameter

Type

Required

Description

code

string

false

We have four predefined filed codes; they are:

PostingDate – date-time value of the transaction

Description – text value of the transaction description

Miles – the number of miles added or subtracted from the account

Info – any other column that we see as part of the history on the prover’s website.

name

string

false

User-friendly name of the field, i.e. “Posting Date” that you can show as the column heading to your end users.

value

string

false

The actual field value, such as "10,000"

Property

In case if the email contains a loyalty account statement that we are able to parse, the individual loyalty account properties will be returned in this array.

Parameter

Type

Required

Description

code

string

false

This is a short, alphanumeric codename do describe this attribute.

name

string

false

User friendly name of the property such as “Account number”. You can display this to your end users.

In addition to travel itineraries, we are able to retrieve loyalty information, such as loyalty account balance, elite status and expiration by parsing data out of email account statements for a select number of loyalty programs. All of the programs that we support and the properties we are able to retrieve are listed using this method.

Please note that AwardWallet supports different providers under different APIs, for instance, the ListProviders method under our Web Parsing API will return a different list of providers.

Array of account transaction history columns that we may gather from emails.

Properties

Parameter

Type

Required

Description

code

string

true

Property code name. Can only have English numbers and letters with no spaces.

name

string

true

User friendly name of a property such as “Account number”. You can display this to your end users.

kind

string

true

Type of property, the possible values are:

0 - Basic property

1 - Account number

3 - Elite Status

4 - Lifetime points

7 - Points / miles earned year-to-date (YTD).

8 - Segments earned year-to-date (YTD).

12 - Name of the account holder, as listed on the account.

13 - Date of the last account activity.

101 - Login information

102 - Partial login information if it was masked in the email

103 - Partial account number if it was masked in the email

Email Scanner

Detect Mailbox Type

Response Example

{"type":"microsoft"}

We support scanning mailboxes via 3 different methods:

IMAP Protocol

Google API

Microsoft API

Since both Google and Microsoft APIs support custom domains (for businesses) you can’t easily tell if a specific email address is managed by either Google Apps or Microsoft Office 365 cloud services. This call will perform the necessary queries to determine if this mailbox is managed by either Google or Microsoft. If it is not, then you need to connect this type of mailbox via the IMAP protocol.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}

GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/detect-type/{email}

Query Parameters

Parameter

Type

Required

Description

email

string

true

Any email address to be tested. This email doesn’t need to be already added to AwardWallet.

Response

Parameter

Type

Required

Description

type

string

true

Tells you how this mailbox should be connected. Can be one of three options: imap, google or microsoft

HTTP Request

Query Parameters

Parameter

Type

Required

Description

startFrom

date

false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean

false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

uri

false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

host

string

false

The IMAP address of the server where we should establish connection. If you omit this parameter we will attempt to detect the IMAP server address automatically for this specific mailbox.

port

integer

false

The IMAP server port. If you omit this parameter we will try to detect the port automatically.

login

string

true

The IMAP server login, in most cases it will be the email address.

password

string

true

The IMAP account password.

secure

boolean

false

Set to true if you want us to use ssl/tls encryption for this mailbox connection and false if you don’t. If you omit this parameter, we will attempt to detect if encryption should be used automatically and will make this decision on our own.

Response

Parameter

Type

Required

Description

id

string

true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string

true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string

true

The current state of the mailbox, there are 5 options:

connecting - you should see this if you just connected a valid mailbox.

error - indicates there was an error while connecting to the mailbox.

scanning - indicates that we are actively scanning messages in the mailbox.

listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.

finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string

false

If the state parameter returns a value of error, this parameter will return one of three error codes:

connection - indicates an error connecting to the mailbox.

authentication - indicates an error authenticating to the mailbox.

unknown - indicates an unknown error.

errorMessage

string

false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

userData

string

false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string

true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string

false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean

false

Shows the value (true or false) that you passed to us when adding the mailbox.

host

string

true

The IMAP address of the server where mailbox is hosted.

login

string

true

The IMAP server login to connect to the mailbox. In most cases it should be the email address.

secure

boolean

false

Shows the value (true or false) for connection type that you passed to us when adding the mailbox. If it was not set then it is true by default.

How you would like to receive events about mailbox scanning progress

Parameter

Type

Required

Description

callbackUrl

uri

true

Endpoint hosted by you where the mailbox events will be sent to. The results will be sent using an HTTP POST method.
The POST body will contain the response in a JSON format.
In production mode, you should register each of your callback hosts with our support.
Each registered callback host can have its own password. We will send this password with every callback using Basic HTTP authorization.
The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

This method should be used to connect any Google mailbox, not just the @gmail.com mailboxes but also any mailboxes hosted by Google Apps. In case you are unsure if a given mailbox is hosted by Google you can call the /mailboxes/detect-type/{email} method.

Using this method to add a Google mailbox is optional. Alternatively you can just use the /mailboxes/start-auth along with the /mailboxes/auth/{code} methods to add a Google mailbox for scanning to our API.

This method utilizes native Google API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:

If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with Google API this way you will get your own googleClientId, googleClientSecret, and googlePubSubTopic. You need to provide those values to our support so that we can have your account updated.

Here are the rough steps that you need to take to create your own verified Google app:

HTTP Request

Query Parameters

Parameter

Type

Required

Description

startFrom

date

false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean

false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

uri

false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

email

string

true

The email address of the mailbox

accessToken

string

true

The access_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

refreshToken

string

true

The refresh_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

Response

Parameter

Type

Required

Description

id

string

true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string

true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string

true

The current state of the mailbox, there are 5 options:

connecting - you should see this if you just connected a valid mailbox.

error - indicates there was an error while connecting to the mailbox.

scanning - indicates that we are actively scanning messages in the mailbox.

listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.

finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string

false

If the state parameter returns a value of error, this parameter will return one of three error codes:

connection - indicates an error connecting to the mailbox.

authentication - indicates an error authenticating to the mailbox.

unknown - indicates an unknown error.

errorMessage

string

false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

userData

string

false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string

true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string

false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean

false

Shows the value (true or false) that you passed to us when adding the mailbox.

email

string

true

The email address of the mailbox that was added as part of the request.

This method should be used to connect any Micosoft mailbox, not just the @live.com, @hotmail.com, or @outlook.com mailboxes but also any mailboxes hosted by Microsoft Office 365. In case you are unsure if a given mailbox is hosted by Microsoft you can call the /mailboxes/detect-type/{email} method.

This method utilizes the native Microsoft API to connect to the mailbox. The end user will get a message requesting access to his or her mailbox which looks like this:

If you don’t want to have AwardWallet mentioned in this message to the end user, you need to create and verify your own app with the Microsoft API this way you will get your own Microsoft Client Id and Microsoft Client Secret. You need to provide those values to our support so that we can have your account updated.

Here are the steps that you need to take to create your own verified Microsoft app. Fisrt, login with your Microsoft account and create a new app if you have not already done so:

You don’t really need to do the guided setup, unless you want to:

Next, generate a new password for your application:

Make sure you safely copy the password, you will need to provide this password to our support in order to allow us to scan your user’s mailboxes:

Then, you need to add a platform, you should select “Web” as the platform:

For the Redirect URLs, you should put https://service.awardwallet.com/email/v2/mailboxes/auth/callback we will handle the response to update this mailbox connection and then will redirect the user to the redirectUrl that you specified in the /mailboxes/start-auth request. You can set the logout URL to be whatever you like on your domain. If you don’t wish to have AwardWallet listed in the Redirect URL you can set that to be your domain, i.e. https://yourdoamin.com/email/callback and then proxy requests sent to this URL to our callback URL. In the end your settings should looks something like this:

For Microsoft Graph Permissions please add profile and User.Read:

Then set the rest of the application profile attributes:

Once your Application is set up you will need to provide AwardWallet support with your App ID / Client Id and your Password/Public Key

HTTP Request

Query Parameters

Parameter

Type

Required

Description

startFrom

date

false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean

false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

uri

false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

email

string

true

The email address of the mailbox

accessToken

string

true

The access_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

refreshToken

string

true

The refresh_token for the OAuth2 connection from Google. You can receive that token yourself from Google and pass it to us or you can have us receive this token directly from Google if you use our /mailboxes/start-auth along with the /mailboxes/auth/{code} methods.

Response

Parameter

Type

Required

Description

id

string

true

The id of the connected mailbox. You would need this id to delete or to update this mailbox connection in the future. You will also be able to get this id from the /mailboxes/ call.

type

string

true

The type of the established connection. Could be one of three values: imap, google, or microsoft.

state

string

true

The current state of the mailbox, there are 5 options:

connecting - you should see this if you just connected a valid mailbox.

error - indicates there was an error while connecting to the mailbox.

scanning - indicates that we are actively scanning messages in the mailbox.

listening - indicates that there are no messages to scan at the moment, so we are listening for new emails to arrive.

finished - indicates that we finished scanning the mailbox and we are not listening for new messages.

errorCode

string

false

If the state parameter returns a value of error, this parameter will return one of three error codes:

connection - indicates an error connecting to the mailbox.

authentication - indicates an error authenticating to the mailbox.

unknown - indicates an unknown error.

errorMessage

string

false

If there is an error the actual error message, such as “Invalid username or password” will be returned via this parameter.

userData

string

false

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

creationDate

string

true

Date and time in UTC when this mailbox was added for scanning.

startFrom

string

false

If the startFrom parameter was passed in the request it will be returned here.

listen

boolean

false

Shows the value (true or false) that you passed to us when adding the mailbox.

email

string

true

The email address of the mailbox that was added as part of the request.

HTTP Request

Query Parameters

Parameter

Type

Required

Description

startFrom

date

false

When adding a mailbox which already contains old emails, you may want to scan those old emails for travel itineraries. This parameter would tell us how far back in time you wish us to go when scanning this mailbox. You can leave this field empty, in that case we will only be scanning this mailbox for new emails going forward, but in that case the listen parameter has to be set to true.

listen

boolean

false

If you want our API to listen for new incoming emails going forward you must set this attribute to true.

callbackUrl

uri

false

Endpoint hosted by you where the parsing results will be sent to. The results will be sent using an HTTP POST method. The POST body will contain the response in a JSON format. In production mode, you should register each of your callback URLs with our support. Each registered callback URL can have its own password. We will send this password with every callback using Basic HTTP authorization. The username will be ‘awardwallet’. You should verify this username and the password on your end, to make sure the request is actually coming from us.

Any text. We will send this text back with each email parsed from this mailbox. You probably want to put your internal User ID in this field so that when we send you parsed travel itineraries from this mailbox you can match them up with the correct user on your end.

tags

array

false

This is an array of strings. You can put any tags you wish to add to this mailbox (i.e. user_123) so that you can then easily find these mailboxes using the List Mailboxes /mailboxes/ method. Please note that you can only put word characters in the tag ([a-zA-Z0-9_]).

provider

string

true

Mailbox provider, against which you wish to authenticate. Can be one of two values: google or microsoft.

redirectUrl

string

true

Upon authentication we will return the user to this URL. We will also pass the following GET parameters in URL state=success&mailboxId=123. In case on an error you wull receive the following parameters: state=error&errorCode=someCode&errorMessage=error+messasge. The errorCode and errorMessage attributes are specific to a provider and returned as-is from Google or Microsoft. It is not recommended to display these values to the end user.

host

string

false

Optional host name which you would set up on your end as a CNAME record pointing to service.awardwallet.com. You only need to do this if you wish to hide a redirect to service.awardwallet.com as part of your users' authentication process. You then need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID.

Response

Parameter

Type

Required

Description

response

string

true

The code that you will need to pass into the user OAuth redirect, i.e. when you send your user to https://service.awardwallet.com/email/v2/mailboxes/auth/{code} for authentication.

User OAuth Redirect

This method can be used to authenticate your users against the Google or Microsoft OAuth APIs. This is not a method you need to call from your servers, instead you need to send your users (via browser) to this URL, it will, then redirect your users to either Google or Microsoft automatically for authentication. After authentication you can see this mailbox being connected to your account via the List Mailboxes (/mailboxes/) method.
After the authentication completes, the user will be redirected to the redirectUrl, specified in /mailboxes/start-auth method. You will then receive the following parameters in the URL:

state: error or success.

errorCode and errorMessage: Technical details about the error. You should not display these fields to the end user, they are designed more for support and troubleshooting purposes.

mailboxId - You will receive this field in case of a successful connection. You could use this field to call the Get Mailbox Info (/mailboxes/{mailboxId}) method.

Get information about a specific mailbox that was added to our mailbox scanner.

HTTP Request

GET https://service.awardwallet.com/email/json/v2/mailboxes/{mailboxId}

GET https://email-eu.awardwallet.com/email/json/v2/mailboxes/{mailboxId}

Query Parameters

Parameter

Type

Required

Description

mailboxId

integer

true

This is the ID that you received from either one of the following methods: List Mailboxes (/mailboxes/), Connect via Google API (/mailboxes/connect/google), Connect via Microsoft API (/mailboxes/connect/microsoft), or the User OAuth Redirect method.

HTTP Request

Query Parameters

Parameter

Type

Required

Description

mailboxId

integer

true

This is the ID that you received from either one of the following methods: List Mailboxes (/mailboxes/), Connect via Google API (/mailboxes/connect/google), Connect via Microsoft API (/mailboxes/connect/microsoft), or the User OAuth Redirect method. You need to pass this parameter in the URL.

If an email contains information about an “operating airline” that is different from the airline listed under the marketingCarrier object, that airline would be defined here. Don’t confuse it with wet lease airline, sometimes wet lease airlines are listed as “operated by” but they are technically not codeshares and would be listed separately in the wetleaseCarrier object.

Wet lease airline is an airline that is DBA (doing business as) the operating airline. It wouldn’t have its own flight number or ticket numbers or confirmation numbers but you may see the wet lease airline listed on the ticket as “ExpressJet” or “KLM Cityhopper”, etc.

Flight duration, as a string, as we gathered it from the provider’s website. Don’t expect to be able to use it programmatically to add or subtract time without some type of transformation on your end that would be specific to each provider.

status

string

false

Status of the segment. I.e. cancelled, confirmed, etc.

meal

string

false

Meal, if any, that will be offered on the flight.

smoking

boolean

false

Most flights nowadays are non-smoking; however, in case if the airline identifies the flight as a smoking flight it would be identified in this field.

stops

integer

false

Number of stops this flight has.

flightStatsMethodUsed

string

false

If FlightStats API was called to retrieve some missing files that are not present in the email and are required for this flight segment the name of the FlightStats API call will be returned in this field. The possible values are:

ScheduleByFlight

ScheduleByRoute

ScheduleByAirport

HistoricalByFlight

HistoricalByRoute

HistoricalByAirport

Aircraft

Parameter

Type

Required

Description

iataCode

string

false

Aircraft IATA code

name

string

true

Aircraft name

turboProp

boolean

false

Indicates if this is a turboprop aircraft

jet

boolean

false

Indicates if this is a jet engine aircraft

wideBody

boolean

false

Indicates if this is a wide-body aircraft

regional

boolean

false

Indicates if this is a regional aircraft

Operating Carrier

Whenever the operating airline is different from the airline listed on the ticket (next to the flight number), that operating airline flight info would be listed in this object as the operating carrier. Don’t confuse this with a wet lease airline.

Airline phone numbers as shown in the email or the number(s) could be populated by AwardWallet automatically based on the airline even if the numbers were not present in the email.

isCodeshare

boolean

false

If this is a codeshare flight and we know the actual operating airline, we would set this attribute to true and then list the actual operating airline (only if it is different from the marketingCarrier.airline) in the operatingCarrier object.

Airline

Parameter

Type

Required

Description

name

string

true

Airline name

iata

string

false

IATA code of the airline

icao

string

false

International Civil Aviation Organization airline code.

Flight Departure or Arrival

This object is describing the arrival or departure events of air travel.

Parameter

Type

Required

Description

airportCode

string

false

If this location happened to be an airport this field will return a Validated IATA airport code.

terminal

string

false

In cases when terminal is known it will be returned in this field.

name

string

true

Train station name or airport name such as “John F. Kennedy International Airport”.

localDateTime

string

true

Local date and time of arrival or departure (depending on the type of this location).

Address

Parameter

Type

Required

Description

text

string

true

Non-validated address string. You can usually use this line to search some API (i.e. Google API) to get detailed / structured information about that address. We usually just grab this text as-is from the provider’s website.

addressLine

string

false

Validated address line of the address (without the city, state, country and zip code) that we got from Google API.

city

string

false

Name of the city validated by the Google API

stateName

string

false

Name of the state validated by the Google API

countryName

string

false

Name of the country validated by the Google API

postalCode

string

false

Zip / postal code validated by the Google API

lat

number

false

Latitude coordinate of the address

lng

number

false

Longitude coordinate of the address

timezone

integer

false

Time zone in which this address is located.

Person

Parameter

Type

Required

Description

name

string

true

Name of the person listed on the reservation.

full

boolean

false

Sometimes passenger or guest names are shortened on the reservation, if we are able to detect it, this field will reflect that. It will be set to true if the we know the name is full (for example John J Smith) and false if the name is shortened, for example (John S.).

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

Reservation confirmation number(s) specific to the parking provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers.

Reservation confirmation number(s) specific to the travel provider. If there are other confirmation numbers specific to a travel agency, those would be listed under the travelAgency. confirmationNumbers. In some cases, there are multiple reservation numbers, for example if there are multiple hotel rooms booked.