AwardWallet Email Parsing API

Full email source, including MIME headers and MIME body

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

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.

The version of the API being used

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.

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

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.

You need to get the requestId from the /parseEmail method

Version of the API being used.

RequestID that corresponds to this email.

Status of the parsing results. The possible values are:

success - The email was successfully parsed

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.

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

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.

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.

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

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.

An array of all itineraries parsed out of the email

Returns the email headers, the entire email, or nothing at all, depending on the value of returnEmail parameter in the request. The value is be base64 encoded.

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 object that describes what was paid for this reservation, i.e. fees, taxes, miles, points, etc.

The method of parsing that was used. There are two possible values:

auto - for automatically parsed emails

manual – for emails that were parsed manually by the AwardWallet team

If we needed to call FlightStats to retrieve some fields that are required and are missing in the email all such FlightStats calls will be listed in this array.

Returns whatever text you sent (as is) in the userData attribute when you created the request.

The name of the FlightStats API method that was called during the parsing. Here are the possible values:

• ScheduleByFlight
• ScheduleByRoute
• ScheduleByAirport
• HistoricalByFlight
• HistoricalByRoute
• HistoricalByAirport

Number of calls made to this method.

Total cost of the reservation including all taxes and fees.

Cost of the reservation before taxes.

Total amount of discounts, if any.

Frequent flier miles, points, or other kinds or bonuses spent on this reservation.

Currency code as gathered from the website. I.e. USD.

Various fees associated with the reservation.

Fee description.

Fee amount.

The sender’s name (if exists) and the email address of the sender.

An array of email recipients listed in the To: field of the email.

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

Email subject.

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.

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

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.

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

The name that is associated with the email address.

The actual email address.

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

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.

Account balance expiration date

Loyalty account username. If the loginMask attribute is set to center, the masked part will be replaced with **, i.e. 12**34. In any other case only the unmasked part will be returned.

Additional login value. A common example would be a country that the loyalty program supports.

This field indicates if the login attribute is masked (for left-hand masking i.e., 1234, the value will be left, for right-hand masking i.e., 1234, the value will be right, for masking the middle part, i.e. 12****34, the value will be 'center')

Account number. If the numberMask attribute is set to center, the masked part will be replaced with **, i.e. 12**34. In any other case only the unmasked part will be returned.

This field indicates if the number attribute is masked (for left-hand masking i.e., 1234, the value will be left, for right-hand masking i.e., 1234, the value will be right, for masking the middle part, i.e. 12****34, the value will be 'center')

This flag indicates that the email does not have any loyalty account attributes in it; however, it confirms that the user is a member of that loyalty program.

We gather as much data as possible from any given account on top of the main attributes like the account balance and its expiration date. These secondary properties will be available in this array.

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 fields as described below.

We have four predefined field 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.

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

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

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

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

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

The actual property value, such as “Silver”

Version of the API being used.

An array of individual providers (that we support with our Email Parsing API) for which we can retrieve travel itineraries (and in some rare cases loyalty information) from emails.

Alpha-numeric value with no spaces that uniquely identifies any given provider.

User friendly display name of the provider. Typically includes both the company name and the name of the loyalty program, i.e. Delta Air Lines (SkyMiles).

Shortened display name of the provider.

Array of ISO 639-1 2-letter language codes which are supported for email parsing for this provider

Estimated number of email formats supported for email parsing for this provider

Array of account properties (secondary attributes) that we may gather from email account statements.

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

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

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

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

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

Tells you how this mailbox should be connected. Can be one of the options: imap, google, microsoft, yahoo, aol

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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

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

The IMAP account password.

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.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

The IMAP address of the server where mailbox is hosted.

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

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.

Type of event

Mailbox information

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

If the onProgress object is set on a mailbox, you will receive an array of MailboxProgressEvent objects, as shown in the example, every time there is a change to the state attribute.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks, we expect to receive code 200. If we get anything another than code 200, we will keep re-trying to send you the response. The page itself can be empty as long as we get code 200.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

The email address of the mailbox

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

The email address of the mailbox

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

The email address of the mailbox

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

The email address of the mailbox

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

Mailbox provider, against which you wish to authenticate. Can be one of the values: google, microsoft, yahoo, aol.

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 will receive the following parameters: state=error&errorCode=someCode&errorMessage=error+message The errorCode and errorMessage attributes are specific to a provider and, in most cases, returned as-is from Google or Microsoft. In case the user did not check the checkbox granting access to their Google mailbox, the error will be custom, as follows: ?state=error&errorCode=missing_mailbox_access&errorMessage=The+user+has+not+granted+the+necessary+read+access+to+this+mailbox It is not recommended to display these values to the end user.

Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint https://service.awardwallet.com/email/v2/mailboxes/auth/callback while preserving all of the query string parameters intact. For example, you should redirect https://your-domain.com/google-callback?code=xxx&error=some+message to https://service.awardwallet.com/email/v2/mailboxes/auth/callback?code=xxx&error=some+message

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.

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.

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 will receive the following parameters: state=error&errorCode=someCode&errorMessage=error+message The errorCode and errorMessage attributes are specific to a provider and, in most cases, returned as-is from Google or Microsoft. In case the user did not check the checkbox granting access to their Google mailbox, the error will be custom, as follows: ?state=error&errorCode=missing_mailbox_access&errorMessage=The+user+has+not+granted+the+necessary+read+access+to+this+mailbox It is not recommended to display these values to the end user.

Optional URL, which you would set up on your domain. You need to add it as an "Authorized Redirect URI" under your OAuth 2.0 client ID. Your end user's browser will be redirected to this URL (after the OAuth authorization is complete). You should then redirect the user from this URL to our endpoint https://service.awardwallet.com/email/v2/mailboxes/auth/callback while preserving all of the query string parameters intact. For example, you should redirect https://your-domain.com/google-callback?code=xxx&error=some+message to https://service.awardwallet.com/email/v2/mailboxes/auth/callback?code=xxx&error=some+message

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.

This is the code that you got from the /mailboxes/start-auth method.

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.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

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 object as JSON in the payload body. It can be one of the two structures already defined in this documentation:

• UpdateOAuthMailboxRequest
• UpdateImapMailboxRequest

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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.

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.

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

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

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

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

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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.

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

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

The IMAP account password.

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.

All callback URLs must be registered with us before use. For production deployments, this is the recommended way to work with our API. So the idea is – you send us a request to update a loyalty account we send you the response as soon as we have it to the callback URL that was sent with the request. We will use http / basic authentication to authenticate ourselves. So when setting up your callback URLs with us, you also need to provide a username (i.e. awardwallet) and a password that we will use to authenticate ourselves when sending callbacks to that URL. We do not need the full path to your endpoint; we do not need the protocol or the port number; all we need is the domain. If your callback URL is https://api.mydomain.com:8080/path/to/my/endpoint, we would only need to register api.mydomain.com. We also support wildcards, so if you have multiple subdomains, we could register *.mydomain.com. We will send headers that look as follows with our callbacks:

Content-type: 'application/json'
Authorization: 'Basic YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI='

where YXdhcmR3YWxsZXQ6YXdkZXZlbG9wZXI= is a base64 encoded string of the username and password separated by a colon, i.e. awardwallet:password

When we send our callbacks to your endpoint, we are expecting a successful response code 2xx. The response body itself can be empty as long as we get code 2xx.

If we get anything other than code 2xx, we will keep trying to send you the response six more times. These retries will happen with the following waiting intervals: 1 minute, 10 minutes, 1 hour, 3 hours, 6 hours and 12 hours between consecutive callback requests until we get a successful response code 2xx.

If the last callback attempt (which will happen approximately 22 hours after the initial callback request) fails to receive a response code 2xx, we will stop trying to send you the data. After that, you can still get the results by calling the /getResults/ method using a requestId attribute.

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

This object allows you to set a callback URL to which we will send changes to the state of a mailbox as soon as they happen, these states are defined in the GetMailbox Info method (such as connecting, listening, error, etc).

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.

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_]).

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

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

This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox state attribute for the list of possible states.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox type attribute for the list of possible types.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox errorCode attribute for the list of possible error codes.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as &emails=John@email.com,Jen@email.com and we will return all the connected mailboxes with this email address as the login value. If a mailbox was connected via IMAP then the login value could be different from the email address; in that case, you would need to specify the login value instead, but this is not common.

An array of Mailbox objects.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. Filter the results using mailbox tags. You can separate different tags with a comma.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the Mailbox state attribute for the list of possible states.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox type attribute for the list of possible types.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. See the mailbox errorCode attribute for the list of possible error codes.

This parameter is passed as a GET parameter in the URL string, not as JSON payload. You can specify more than 1 email address (comma separated) such as &emails=John@email.com,Jen@email.com and we will return all the connected mailboxes with this email address as the login value. If a mailbox was connected via IMAP then the login value could be different from the email address; in that case, you would need to specify the login value instead, but this is not common.

The value that you got in the nextPageToken attribute from the previous request.

An array of Mailbox objects.

Please pass this value to the next pageToken parameter of the subsequent request to fetch the next page.

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.

Revoke tokens for oauth mailboxes, default false