API Endpoints – Help Center

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

Sign in to your SmarterSends instance.
Go to Settings -> Integrations, then select API.
Click Generate API Key.
Copy the new key shown. You will only see the full key once; store it in a secure location (e.g., a secrets manager).
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

Create a new request: GET https://your-instance-domain.smartersends.com/api/usage/campaigns/export
Params: add your query parameters (e.g., start_date, end_date, format).
Auth tab: choose Bearer Token and paste your API key.
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.

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.

Conversations Usage API

Use this endpoint to retrieve Two-Way Conversations usage metrics and a by-group rollup for a date range. This is the same dataset shown in Usage Reports → Conversations.

Endpoint

GET /api/usage/conversations

Authentication

Use a Bearer token API key in the request header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

Optional

start_date — Inclusive start of the date window. Accepts common date formats (e.g., 2026-01-01, 2026-01-01 00:00:00, or ISO 8601).
end_date — Inclusive end of the date window. Accepts common date formats.
format — Output format. Allowed: json (default) or csv.

Defaults

If omitted:

start_date defaults to 30 days ago
end_date defaults to today
format defaults to json

Filters Applied

The report is filtered by conversations.created_at between start_date and end_date (inclusive).

Output (JSON)

When format=json (default), the API returns JSON with:

range: ISO8601 start/end
metrics: overall counts and averages
by_group: per-group rollup rows

Metrics fields

total_conversations
active_conversations
awaiting_reply
unread_conversations
at_risk
stale
reminders
escalations
avg_first_response_minutes (nullable)
avg_messages_per_conversation
avg_sent_messages_per_conversation
avg_received_messages_per_conversation

By-group fields

Each row contains:

group_id
group_name
total_conversations
active_conversations
awaiting_reply
unread_conversations
at_risk
stale
reminders
escalations
avg_first_response_minutes (nullable)
avg_messages_per_conversation

Output (CSV export)

When format=csv, the export is generated on the server, uploaded to private object storage, and the API returns JSON containing a temporary signed download URL.

The CSV file contains:

A metrics section (metric,value)
A blank row
A by_group table (one row per group)

Response (CSV mode)

The response contains file metadata and a temporary URL (when supported by your storage driver):

{
  "file": {
    "extension": "csv",
    "content_type": "text/csv",
    "s3_path": "/tmp/exports/{tenantId}/conversations_usage_YYYYMMDD_HHMMSS_UUID.csv",
    "url": "https://...temporary-signed-url...",
    "expires_at": "2026-01-26T15:10:00Z"
  }
}

Examples

cURL (JSON)

curl -X GET \
  "https://your-instance-domain.smartersends.com/api/usage/conversations?start_date=2026-01-01&end_date=2026-01-31&format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

cURL (CSV export)

curl -X GET \
  "https://your-instance-domain.smartersends.com/api/usage/conversations?start_date=2026-01-01&end_date=2026-01-31&format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Troubleshooting

401 Unauthorized: Missing/invalid API key. Ensure the Authorization: Bearer header is present.
400/422 Validation: Invalid dates or an unsupported format value.
Empty results: Check your start_date / end_date range.

Notes

The report scope is based on conversation create date (conversations.created_at), not “last updated” or “last message”.
Temporary URLs typically expire after ~60 minutes.

Events API

The Events API allows you to programmatically manage events in your SmarterSends calendar. Events can be one-time or recurring and can be targeted to specific groups or all groups within your instance.

Authentication

All requests must include a valid Bearer Token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints

List Events
Create Event
Get Event
Update Event
Delete Event

List Events

Retrieve a list of all events for your instance.

Endpoint

GET /api/events

Success Response

[
  {
    "id": 1,
    "name": "Team Sync",
    "start_date": "2026-02-01T09:00:00.000000Z",
    "end_date": "2026-02-01T10:00:00.000000Z",
    "description": "Weekly team sync meeting",
    "repeats": false,
    "repeat_type": null,
    "max_occurrences": null,
    "repeat_interval": null,
    "repeat_days": null,
    "repeat_months": null,
    "all_groups": true,
    "created_at": "2026-01-28T16:00:00.000000Z",
    "updated_at": "2026-01-28T16:00:00.000000Z",
    "groups": []
  }
]

Create Event

Create a new one-time or recurring event.

Endpoint

POST /api/events

Required Parameters

name (string) — The name of the event.
start_date (string) — The start date and time (ISO 8601 format recommended).

Optional Parameters

end_date (string) — The end date and time.
description (string) — A detailed description of the event.
repeats (boolean) — Whether the event repeats. Default: false.
repeat_type (string) — Frequency of repetition. Allowed: daily, weekly, monthly, yearly.
repeat_interval (integer) — Interval between repetitions (e.g., every 2 weeks).
max_occurrences (integer) — Maximum number of times the event should occur.
repeat_days (array) — For weekly events, which days to repeat on (e.g., ["MO", "WE", "FR"]).
repeat_months (array) — For yearly events, which months to repeat in (e.g., [1, 7]).
all_groups (boolean) — If true, the event is visible to all groups.
groups (array) — An array of Group IDs to associate this event with.

Request Example (Recurring Event)

{
  "name": "Weekly Training",
  "start_date": "2026-02-02T14:00:00Z",
  "repeats": true,
  "repeat_type": "weekly",
  "repeat_interval": 1,
  "repeat_days": ["MO"],
  "groups": [5, 12]
}

Get Event

Retrieve details for a specific event.

Endpoint

GET /api/events/{id}

Success Response

{
  "id": 1,
  "name": "Team Sync",
  ...
  "groups": [
    { "id": 5, "name": "Marketing" }
  ]
}

Update Event

Update an existing event. Only provided fields will be updated.

Endpoint

PUT /api/events/{id}

Parameters

Accepts the same parameters as the Create Event endpoint.

Delete Event

Remove an event from the calendar.

Endpoint

DELETE /api/events/{id}

Success Response

204 No Content

Error Handling

401 Unauthorized: Missing or invalid API key.
404 Not Found: The specified event ID does not exist.
422 Unprocessable Entity: Validation failed (e.g., missing required fields or invalid date format).

Authentication

Create an API Key

Making Requests

Base Path

Example: Export Campaign Usage

cURL Example (JSON export)

Postman Setup

Error Handling & Troubleshooting

Security Best Practices

FAQ

Can I see my API key again later?

Where do I find the list of available routes?

Endpoints

Campaign Export API

Endpoint

Request

Required Parameters

Optional Parameters

Filters Applied

Output

Response

Examples

Export CSV with defaults

Export JSON with custom columns

Export CSV filtered by type and status (case-insensitive, multi)

Behavior Details

Troubleshooting

Conversations Usage API

Endpoint

Authentication

Query Parameters

Optional

Defaults

Filters Applied

Output (JSON)

Metrics fields

By-group fields

Output (CSV export)

Response (CSV mode)

Examples

cURL (JSON)

cURL (CSV export)

Troubleshooting

Notes

Events API

Authentication

Endpoints

List Events

Endpoint

Success Response

Create Event

Endpoint

Required Parameters

Optional Parameters

Request Example (Recurring Event)

Get Event

Endpoint

Success Response

Update Event

Endpoint

Parameters

Delete Event

Endpoint

Success Response

Error Handling

Related articles