GetThru API for Account-Level Exports
GetThru offers an API endpoint that gives you your daily messages export or your daily opt out export each night. The API provides access to CSV files similar to those available through GetThru's automated nightly S3 exports. Each request returns a temporary download link for the most recently completed export. You can use this API to integrate GetThru data with your own databases, reporting tools, or other systems.
For an alternative method of retrieving automated exports, see Automated Nightly Data Reports with AWS S3.
TABLE OF CONTENTS
Exports
The API supports two account-level exports:
- Daily Messages: Incoming and outgoing SMS and MMS messages from your ThruText campaigns.
- Daily Opt Outs: Opt out records associated with contacts in your ThruText account.
For details on what the exports contain, read our guide, ThruText Export Types.
Request API Access
To get started, email support@getthru.io and request API access for your GetThru account. Once the API is enabled, GetThru will provide your account-specific endpoint URL and a unique authentication token through OneTimeSecret. A OneTimeSecret link opens only once, so save the token in a secure place right away.
A token expires one year after GetThru creates it. GetThru staff contact you shortly before it expires and send a new one.
Request an Export
To retrieve an export, send an HTTP GET request to your account's API endpoint using your API token.
Endpoint
GET https://getthru.app/api/v0/accounts/{domain}/exports/{type} |
The endpoint contains the following values:
| Parameter | Description |
|---|---|
{domain} | The domain of your GetThru account. It must match the account of your token. Your domain can be found from the URL from your dashboard: https://getthru.app/account/[domain]/admin |
{type} |
|
The domain and export type are case-sensitive.
Authentication
Include your API token in the Authorization header using the following format:
Authorization: Bearer <your API token> |
The word Bearer is also case-sensitive.
Example Request
The following example retrieves the daily-opt-out export using curl:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \ "https://getthru.app/api/v0/accounts/<your domain>/exports/daily-opt-outs" |
Replace the placeholder values with the credentials and URL provided by GetThru.
Example Response
A successful request returns HTTP 200 with a JSON response:
{
"url": "https://..."
} |
The url field holds a temporary download link to a CSV file. The download link expires 5 minutes after the response. Download the file right away. If the link expires, send the request again to get a new link.
Responses
| Status | Meaning | What to do |
|---|---|---|
| 200 OK | A file is ready. The url field holds a download link | Download the file within 5 minutes. |
| 401 Unauthorized | The Authorization header is missing, or the token is wrong or expired. | Check the header format. If the token is more than a year old, contact support for a new one. |
| 403 Forbidden | The domain in the URL is not the domain of the token's account. | Use the exact URL that GetThru sent you. |
| 404 Not found | The type is not daily-messages or daily-opt-outs, or no file of that type is ready for your account. | Check the type. If the type is correct, contact support to confirm that the export is turned on. |
| 500 Internal Server Error | An error occurred on the GetThru side. | Try again later. If the error continues, contact support. |
When Files Are Available
GetThru begins generating daily exports at midnight UTC. Each export covers the previous calendar day, from 00:00 UTC up to, but not including, 00:00 UTC the following day. Files take additional time to generate and may not be available immediately after midnight. The API retrieves an existing completed export rather than generating a new one when you make a request.
Keep in mind:
- The API does not support requesting exports for a specific date.
- Only the latest eligible completed export of each type is available through the API.
- Previous files cannot be retrieved through the API after a newer export replaces them.
- If a new file is not ready, the API may return an earlier completed export.
- If you're automating downloads, we recommend monitoring your integration for missed or unsuccessful downloads to avoid gaps in your data.
We recommend scheduling requests a few hours after midnight UTC and confirming the reporting period from the file name before importing each file.
Manage Your API Token
API tokens expire one year after they are created. GetThru will contact you shortly before your token expires to provide a replacement.
Store your token securely and update your integration when you receive a new one to avoid interruptions. Treat both your API token and temporary download URLs as sensitive information. Do not share them publicly or include them in publicly accessible code.