Skip to main content

API Endpoints

Sam Lewis
Updated

The SmarterSends API allows your internal systems to securely retrieve data from your instance. This guide explains how to create an API key and authenticate requests to available API routes.

Instance-specific base URL: Replace https://your-instance-subdomain.smartersends.com with your actual instance URL when calling the API.

Authentication

SmarterSends uses Bearer Token authentication. You must include an Authorization header with a valid API key for every request:

Authorization: Bearer YOUR_API_KEY
Important: API keys grant access to your data. Store them securely, never hard-code them in client-side code, rotate them regularly, and revoke keys that are no longer needed.

Create an API Key

  1. Sign in to your SmarterSends instance.
  2. Go to Settings -> Integrations, then select API.
  3. Click Generate API Key.
  4. Copy the new key shown. You will only see the full key once; store it in a secure location (e.g., a secrets manager).
  5. Optionally, you can delete (revoke) an existing key from the same screen.

The integration panel also shows when each key was created and the last time it was used.

 

Making Requests

Base Path

API endpoints live under the path: /api. Example base: https://your-instance-domain.smartersends.com/api

 

Example: Export Campaign Usage

cURL Example (JSON export)

curl -X GET \
  "https://your-instance-domain.smartersends.com/api/usage/campaigns/export?start_date=2025-01-01&end_date=2025-01-31&format=json&columns=name,subject,send_time,type,status,template_name" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Postman Setup

  1. Create a new request: GET https://your-instance-domain.smartersends.com/api/usage/campaigns/export
  2. Params: add your query parameters (e.g., start_date, end_date, format).
  3. Auth tab: choose Bearer Token and paste your API key.
  4. Send the request.

 

Error Handling & Troubleshooting

  • 401 Unauthorized: Missing or invalid API key. Ensure the Authorization: Bearer header is present and the key is correct.

  • 400/422 Validation: Check that required parameters are included and properly formatted (e.g., start_date, end_date).

     

Security Best Practices

  • Keep API keys secret. Use a server-side integration or a secure secrets manager.
  • Rotate keys regularly. Revoke old keys via Settings -> Integrations -> API.
  • Use HTTPS for all API calls.

  • Limit who has access to view or generate API keys in your organization.

     

FAQ

Can I see my API key again later?

No. For security reasons, the full key is only shown once at creation. If you lose it, delete the old key and generate a new one.

Where do I find the list of available routes?

Routes are added over time. The example above shows the /api/usage/campaigns/export endpoint. All available endpoints will be documented below.

 

Endpoints

 

 

Campaign Export API

Use this endpoint to export campaigns within a date range as a CSV (default) or JSON file. The export is generated asynchronously on the server, uploaded to private object storage, and a temporary download URL is returned.

Endpoint

POST /api/usage/campaign/export

Request

Send a POST request with query string parameters or a JSON body. The following parameters are supported:

Required Parameters

  • start_date — The inclusive start of the date/time window used to filter campaigns by send_time. Accepts common date-time formats (e.g., 2025-01-01 or 2025-01-01 00:00:00 or ISO 8601).
  • end_date — The inclusive end of the date/time window used to filter by send_time. Accepts common date-time formats (e.g., 2025-12-31 or 2025-12-31 23:59:59 or ISO 8601).

Optional Parameters

  • type — Filters by campaign type (exact match: email or sms). If omitted, all types are included.
  • status — A comma-separated list of statuses to include. Case-insensitive; invalid entries are ignored; duplicates are removed. Allowed values: Draft, Sent, Canceled, Failed, Pending, Scheduled, Reviewed. Example: status=sent,scheduled.
  • date_column – The column to use for the date range. Allowed values: created_at, updated_at, send_time (default). Example: date_column=created_at.
  • format — The export format. Allowed: csv (default), json.

  • columns — A comma-separated list of columns to include in the export (order is preserved; duplicates are removed). Case-insensitive; spaces are converted to underscores; unrecognized columns are ignored. If, after filtering, no valid columns remain, the default set is used.

    Defaults: name, subject, send_time, type, html

    Allowed columns: name, subject, send_time, type, html, from_name, from_address, reply_to_address, status, sent_mailing_id, template_name, group_name, user_name

Filters Applied

  • Date Range: Only campaigns with send_time between start_date and end_date (inclusive) are exported.
  • Type: If provided, only campaigns with an exact type match are exported.
  • Status: If provided, only campaigns whose status is in the allowed list above are exported.

Output

  • CSV: First row contains the selected column headers. send_time is formatted as YYYY-MM-DD HH:mm:ss. 
  • JSON: An array of objects, each keyed by the selected columns. send_time is formatted as YYYY-MM-DD HH:mm:ss.

Response

The API responds with JSON containing the exported file metadata and a temporary, signed download URL (when supported by storage). URLs typically expire after 60 minutes.

{
  "file": {
    "extension": "csv|json",
    "content_type": "text/csv|application/json",
    "s3_path": "/tmp/exports/{tenantId}/campaigns_YYYYMMDD_HHMMSS_UUID.csv",
    "url": "https://...temporary-signed-url...",
    "expires_at": "2025-10-16T17:10:00Z"
  },
  "message": "Export generated, but no temporary URL could be created." // Present only if a URL couldn't be generated
}

Examples

Export CSV with defaults
POST /api/usage/campaign/export?start_date=2025-01-01&end_date=2025-01-31
Export JSON with custom columns
POST /api/usage/campaign/export?start_date=2025-01-01 00:00:00&end_date=2025-01-31 23:59:59&format=json&columns=name,subject,send_time,status,template_name
Export CSV filtered by type and status (case-insensitive, multi)
POST /api/usage/campaign/export?start_date=2025-06-01&end_date=2025-06-30&type=email&status=sent,SCHEDULED,invalid_status

Behavior Details

  • Column normalization: The columns parameter is split by commas, trimmed, converted to lowercase, and spaces are replaced with underscores. Only allowed columns are kept; duplicates are removed while preserving order. If none remain, the default column set is used.
  • Status normalization: Values are trimmed, case-normalized, validated against the allowed list, de-duplicated, and applied with an IN filter.
  • Performance: Exports stream results in chunks to a temporary file before upload, enabling large dataset exports.
  • URL expiry: Temporary URLs typically expire after 60 minutes.

Troubleshooting

  • Empty export: Verify your start_date/end_date, type, and status filters—overly restrictive filters may return no data.
  • Invalid columns ignored: If you request columns outside the allowed list, they are silently dropped. The default columns are used if no valid columns remain.

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk