Airship Integration

In this article, we’ll walk through integrating your SmarterSends instance with an Airship project. The API portion can typically be completed in 15 minutes. Configuring Real-Time Data Streaming for campaign reporting may take additional time.

You’ll find the integration settings in SmarterSends under Integrations -> Email.

Before you begin, you’ll need:

1. Access to your Airship project as an Owner or Administrator.
2. Your Airship region.
3. Your Airship App Key and Master Secret.
4. Airship OAuth client credentials.
5. An Airship Real-Time Data Streaming Amazon S3 integration.
6. Access to your SmarterSends instance as an account owner.

Log in to both Airship and SmarterSends before starting.

1. App Key and Master Secret

SmarterSends uses the App Key and Master Secret for server-to-server communication with the Airship API.

1. Open the appropriate project in the Airship dashboard.
2. Next to the project name, open the project menu and select Project Details. In some Airship accounts, these credentials may appear under Settings -> APIs & Integrations.
3. Locate the App Key and Master Secret.
4. Copy the App Key into the App Key field in SmarterSends.
5. Copy the Master Secret into the Master Secret field in SmarterSends.
6. Do not use the App Secret in place of the Master Secret.

The Master Secret provides broad access to the Airship API and should only be stored in trusted server-side systems. Do not place it in an application, template, or publicly accessible location.

Airship API security documentation:
https://www.airship.com/docs/guides/getting-started/developers/api-security

2. Select Your Airship Region

Select the Airship region associated with your project:

1. United States
2. European Union

The selected region determines which Airship API endpoints SmarterSends uses. Choosing the wrong region will cause API authentication to fail.

3. Create OAuth Client Credentials

SmarterSends uses Airship OAuth client credentials to request short-lived access tokens and verify access to your Airship channels.

1. In Airship, open the menu next to your project name and select Settings.
2. Under Project Settings, select OAuth.
3. Select Add Credentials.
4. Enter a recognizable name, such as “SmarterSends.”
5. Add a description explaining that the credentials are used by the SmarterSends integration.
6. Enable Allow Basic Auth.

Allow Basic Auth must be enabled. This generates the Client Secret required by SmarterSends.

7. Optionally configure an expiration date. If you set an expiration date, the credentials must be replaced in SmarterSends before they expire.
8. Select Next.
9. Enable the Channels permission, identified by the OAuth scope “chn.”
10. Select Save.
11. Copy the Client ID and Client Secret before closing the credentials window.

Airship displays the Client Secret only when the credentials are created. Store it securely.

12. In SmarterSends, enter the Client ID in the OAuth Client ID field.
13. Enter the Client Secret in the OAuth Client Secret field.
14. Enter the following value in the OAuth Scopes field:

chn

Airship OAuth documentation:
https://www.airship.com/docs/developer/rest-api/ua/operations/oauth/

4. Configure Real-Time Data Streaming

SmarterSends uses Airship Real-Time Data Streaming, or RTDS, to collect recipient-level campaign events and update mailing statistics.

Your Airship account must include access to both Messaging and Real-Time Data Streaming.

Contact SmarterSends Support for the Amazon S3 bucket information required for your organization before creating the connection.

To configure the integration:

1. In Airship, open the menu next to your project name and select Settings.
2. Under Project Settings, select Real-Time Data Streaming.
3. Select Amazon S3.
4. Create an outbound Amazon S3 integration using the connection details provided by SmarterSends.
5. Select JSON as the output format.

SmarterSends processes JSON event files. Do not select CSV.

6. Include the messaging delivery and engagement events needed for reporting, including sends, deliveries, opens, clicks, bounces, unsubscribes, SMS delivery reports, and SMS short-link clicks where applicable.
7. Complete and enable the integration.
8. Locate the Integration ID assigned by Airship.
9. Copy this value into the RTDS S3 Integration ID field in SmarterSends.

Airship stores the files using a path containing the App Key and Integration ID. Both values must match the values entered in SmarterSends.

Airship Amazon S3 integration documentation:
https://docs.airship.com/integrations/aws/

5. Configure Stats Scan Days

Stats Scan Days controls how many recent Airship S3 date folders SmarterSends checks for unprocessed event files.

The recommended starting value is:

2

Increase this value if event files are frequently delayed by more than one day. Increasing it causes SmarterSends to inspect more S3 folders during each scan, but previously processed files will not be counted twice.

6. Test API Access

After entering the required settings:

1. Click Test API Access.
2. SmarterSends will validate the App Key and Master Secret.
3. SmarterSends will request an OAuth access token and verify access to the Airship Channels API.
4. Confirm that API Access Successful displays a green checkmark.

If validation fails, verify:

1. The correct United States or European Union region is selected.
2. The App Key and Master Secret belong to the same Airship project.
3. The Master Secret was entered instead of the App Secret.
4. Allow Basic Auth was enabled when the OAuth credentials were created.
5. The OAuth Client ID and Client Secret were copied correctly.
6. The OAuth credentials are active and have not expired.
7. The OAuth Scopes field contains “chn.”
8. Configure Custom Attributes

After API access is validated, SmarterSends displays the Custom Attributes section.

Add each Airship custom attribute that should be available for queries, personalization, or Group contact restrictions.

For each attribute, enter:

1. Attribute Name

Enter the exact attribute key used by Airship. Attribute names are case-sensitive.

2. Attribute Friendly Name

Enter the label SmarterSends users should see when selecting the attribute.

3. Attribute Type

Select the corresponding Airship data type:

• String
• Number
• Date

Make sure the selected type matches the data stored in Airship. An incorrect type can cause audience criteria to return unexpected results or be rejected by Airship.

Select Add Attribute to configure additional attributes.

8. Save the Integration

After API Access Successful displays a green checkmark and the custom attributes are configured:

1. Click Save.
2. Return to the Integrations page.
3. Confirm that the Email integration displays Connected.
4. Airship Audience Behavior

Airship Segments are available as campaign audiences within SmarterSends.

When building a campaign:

1. At least one Airship Segment must be selected as the audience.
2. If multiple audience Segments are selected, contacts matching any selected Segment are included.
3. Suppression Segments are excluded from the campaign audience.
4. Seed Segments are sent as a separate Airship send.
5. Group contact restrictions are added to primary live campaign sends.
6. Group contact restrictions are not applied to Seed list sends or individual test sends.
7. Verifying the Integration

After completing the setup, we recommend performing the following checks:

1. Create a campaign and confirm your Airship Segments appear in the audience selector.
2. Send a test email and confirm it is received.
3. If using SMS, confirm the test number is already registered and opted in within Airship.
4. If using push notifications, test using an existing Airship Named User ID.
5. Send a live campaign to a controlled audience.
6. Confirm the send appears in Airship.
7. Allow time for Airship RTDS files to be delivered to Amazon S3.
8. Confirm delivery and engagement statistics begin appearing in SmarterSends.

Troubleshooting

API Access Failed

Confirm the region, App Key, Master Secret, OAuth credentials, and OAuth scope. If the OAuth Client Secret is no longer available, create new OAuth credentials with Allow Basic Auth enabled.

Segments Are Not Available

Confirm that API access is successful and that the configured Airship project contains active Segments.

Statistics Are Not Appearing

Confirm that the Airship Amazon S3 integration is enabled, JSON output is selected, the correct events are included, and the RTDS S3 Integration ID exactly matches the Airship integration.

SMS Test Sends Fail

Airship requires test SMS recipients to already be registered and opted in for the configured sender. Confirm the phone number and sender configuration in Airship.

Authentication Previously Worked but Now Fails

Check whether the OAuth client credentials expired or were revoked. If necessary, create replacement credentials and update the OAuth Client ID and Client Secret in SmarterSends.