logo
API docs by Redocly

SendFox API (1.4.0)

Download OpenAPI specification:Download

Introduction

SendFox's REST API lets you manage contacts, campaigns, lists, automations, and forms programmatically. It uses OAuth 2.0 for authentication.

Compatible with AI agents (Claude, ChatGPT, etc.) via the OpenAPI spec. Available at GET /openapi.yaml.

Authentication

Personal Access Token

Create a personal access token at https://sendfox.com/account/oauth. Once created, use it in the Authorization header:

Authorization: Bearer {TOKEN}

OAuth 2.0 Client

For integrations that require user authentication, create an OAuth 2.0 client at https://sendfox.com/account/oauth

Rate Limits

API requests are limited to 60 requests per minute per authenticated user. Rate limit status is returned in response headers:

  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in current window
  • Retry-After: Seconds until rate limit resets (only on 429 responses)

Error Responses

All error responses use standard HTTP status codes and Laravel's default error format:

  • message: Human-readable error description
  • errors: Field-level validation errors (on 422 responses)

Plans & API Access

API access requires a Lifetime or Empire plan. Free users cannot use the API.

Accounts restricted by SendFox cannot use authenticated API endpoints. These requests return 403 Forbidden with the error code account_restricted and a link to the account status page.

Contacts

List contacts

Returns a paginated list of contacts (100 per page by default, up to 1000 via per_page).

Supports engagement filtering through filter[...] query parameters, so you can answer questions like "who last opened over a year ago" without paging the whole account. All filter conditions are AND-ed. Pass count_only=true to get just the number of matches — the cheapest way to size an audience before acting on it.

Authorizations:
oauth2
query Parameters
query
string

Search query for filtering contacts

unsubscribed
boolean

Filter unsubscribed contacts

email
string

Filter by specific email

per_page
integer [ 1 .. 1000 ]
Default: 100

Contacts per page

count_only
boolean

Return only the number of matching contacts, with no contact records

filter[status]
string
Enum: "active" "engaged" "inactive" "new" "unconfirmed" "unsubscribed" "bounced" "invalid"

Engagement status

filter[last_opened_after]
string <date-time>

Contacts whose most recent open is on or after this date

filter[last_opened_before]
string <date-time>

Contacts whose most recent open is before this date. Excludes contacts who never opened — use filter[never_opened] for those.

filter[last_clicked_after]
string <date-time>

Contacts whose most recent click is on or after this date

filter[last_clicked_before]
string <date-time>

Contacts whose most recent click is before this date

filter[last_sent_after]
string <date-time>

Contacts last sent to on or after this date

filter[last_sent_before]
string <date-time>

Contacts last sent to before this date

filter[created_after]
string <date-time>

Contacts created on or after this date

filter[created_before]
string <date-time>

Contacts created before this date

filter[never_opened]
boolean

Only contacts who have never opened an email

filter[never_clicked]
boolean

Only contacts who have never clicked a link

filter[never_sent]
boolean

Only contacts who have never been sent an email

filter[in_list_ids]
Array of integers

Only contacts in any of these lists

filter[not_in_list_ids]
Array of integers

Exclude contacts in any of these lists

filter[tag_ids]
Array of integers

Only contacts carrying any of these tags

filter[not_tag_ids]
Array of integers

Exclude contacts carrying any of these tags

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "filter": "string"
}

Create a new contact

Authorizations:
oauth2
Request Body schema: application/json
email
required
string <email>
first_name
string
last_name
string
ip_address
string
lists
Array of integers

Array of list IDs to add the contact to

Array of objects

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "lists": [
    ],
  • "contact_fields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a specific contact

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a contact

Update contact details including name, list memberships, and custom fields

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
first_name
string
last_name
string
lists
Array of integers

Array of list IDs (replaces all current list memberships)

Array of objects

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "lists": [
    ],
  • "contact_fields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a contact

Soft-deletes a contact and cancels any scheduled deliverables

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get email activity for a contact

Returns paginated email deliverables and contact-level engagement summary

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "contact": {
    },
  • "deliverables": {
    }
}

Batch import contacts

Import up to 1,000 contacts in a single request. Creates new contacts or updates existing ones.

Authorizations:
oauth2
Request Body schema: application/json
required
Array of objects <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "contacts": []
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0
}

Apply a tag or list change to every contact matching a filter

Queues one action against every contact the filter matches, applied in chunks in the background. Returns immediately with an id to poll.

Run with dry_run: true first. A dry run reports how many contacts match and changes nothing — it is the only way to catch a filter that matches more than intended, and a bulk write is not undoable. An empty filter (which would match the whole account) is rejected unless it is a dry run.

Per-campaign conditions (opened_campaign_id, not_opened_campaign_id, clicked_campaign_id) are available here but not on GET /contacts, because they are resolved in the background rather than inside a request.

Bulk delete and bulk unsubscribe are deliberately not offered.

Authorizations:
oauth2
Request Body schema: application/json
action
required
string
Enum: "apply_tag" "remove_tag" "add_to_list" "remove_from_list"
target_id
required
integer

The tag id (apply_tag/remove_tag) or list id (add_to_list/remove_from_list)

dry_run
boolean
Default: false

When true, only count the matches — nothing is modified

object (ContactFilter)

An engagement filter over the account's contacts. Every condition is AND-ed. Omitting the object entirely means "all contacts".

Responses

Request samples

Content type
application/json
{
  • "action": "apply_tag",
  • "target_id": 0,
  • "dry_run": false,
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "pending",
  • "action": "apply_tag",
  • "target_id": 0,
  • "dry_run": true,
  • "filter": "string",
  • "matched_count": 0,
  • "processed_count": 0,
  • "error": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

Check the progress of a bulk contact action

For a dry run, matched_count is the answer and nothing was modified. A run whose match set exceeds the per-request ceiling fails without applying anything.

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "pending",
  • "action": "apply_tag",
  • "target_id": 0,
  • "dry_run": true,
  • "filter": "string",
  • "matched_count": 0,
  • "processed_count": 0,
  • "error": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z"
}

List unsubscribed contacts

Authorizations:
oauth2
query Parameters
query
string

Search query for filtering contacts

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Unsubscribe a contact by email

Authorizations:
oauth2
Request Body schema: application/json
email
required
string <email>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Campaigns

List campaigns

Returns a paginated list of campaigns (100 per page)

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Create a new campaign

Creates a campaign as a draft. To send it, use the send endpoint or provide scheduled_at. Subject lines cannot start with "RE:" or "FWD:". At least one list is required if scheduled_at is provided.

Authorizations:
oauth2
Request Body schema: application/json
title
required
string <= 191 characters
subject
required
string <= 191 characters
preview_text
string or null <= 191 characters

Inbox preview snippet shown beneath the subject line. Optional.

html
required
string <= 1000000 characters

Email body HTML content

from_name
required
string <= 191 characters
from_email
required
string <email> <= 191 characters
scheduled_at
string <date-time>

Schedule send time (omit for draft). Must include at least one list.

lists
Array of integers

Array of list IDs to send to

excluded_lists
Array of integers

List IDs whose contacts should be excluded from the send. Exclusion wins over inclusion.

to_contact_tags
Array of integers

Tag IDs whose contacts should receive the campaign. Can be combined with lists.

excluded_contact_tags
Array of integers

Tag IDs whose contacts should be excluded from the send. Exclusion wins over inclusion.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "lists": [
    ],
  • "excluded_lists": [
    ],
  • "to_contact_tags": [
    ],
  • "excluded_contact_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a specific campaign

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a draft campaign

Only draft campaigns (not yet sent) can be updated. All fields are optional.

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
title
string <= 191 characters
subject
string <= 191 characters
preview_text
string or null <= 191 characters

Inbox preview snippet. Pass null to clear.

html
string <= 1000000 characters
from_name
string <= 191 characters
from_email
string <email> <= 191 characters
scheduled_at
string or null <date-time>

Set to null to unschedule, or a datetime to schedule

lists
Array of integers

Replaces all list assignments

excluded_lists
Array of integers

Replaces the excluded lists (contacts in these lists are removed from the send).

to_contact_tags
Array of integers

Replaces the included tag audience (contacts carrying these tags receive the campaign).

excluded_contact_tags
Array of integers

Replaces the excluded tag audience (contacts carrying these tags are removed from the send).

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "lists": [
    ],
  • "excluded_lists": [
    ],
  • "to_contact_tags": [
    ],
  • "excluded_contact_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a draft campaign

Only draft campaigns (not yet sent) can be deleted. Uses soft delete.

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a campaign immediately

Schedules a draft campaign for immediate sending. The campaign must:

  • Not already be sent or scheduled
  • Have at least one list assigned
  • The user must not be in a warmup/throttle period

All existing abuse prevention applies automatically: content approval workflow, sending throttles, spam detection, and bounce rate monitoring.

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get campaign performance statistics

Returns sent count and open/click/bounce/unsubscribe/spam counts and rates, all read from stored counters.

Pass include_link_stats=true to also get link_stats — the campaign's links ranked by click count. That part is opt-in because it counts rows in email_link_clicks once per link rather than reading a counter, so leaving it off keeps this endpoint as cheap as it has always been.

Authorizations:
oauth2
path Parameters
id
required
integer
query Parameters
include_link_stats
boolean
Default: false

When true, include the link_stats breakdown in the response

link_limit
integer [ 1 .. 100 ]
Default: 50

How many links to return in link_stats, most-clicked first. Ignored unless include_link_stats is true.

Responses

Response samples

Content type
application/json
{
  • "link_stats": [
    ],
  • "sent_count": 0,
  • "unique_open_count": 0,
  • "unique_click_count": 0,
  • "unsubscribe_count": 0,
  • "bounce_count": 0,
  • "spam_count": 0,
  • "open_rate": 0,
  • "click_rate": 0,
  • "unsubscribe_rate": 0,
  • "bounce_rate": 0,
  • "spam_rate": 0
}

List the contacts behind a campaign's engagement

Returns the contacts in one of a sent campaign's engagement groups. non_openers covers contacts the campaign actually sent to who did not open it — queued and cancelled deliverables are excluded, since they never had the chance.

Authorizations:
oauth2
path Parameters
id
required
integer
query Parameters
type
required
string
Enum: "openers" "clickers" "non_openers" "bounced" "unsubscribed"

Which engagement group to list

per_page
integer [ 1 .. 1000 ]
Default: 100

Records per page

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Clone a sent campaign at part of its original audience

Creates a new draft with the original's content, sender, and exclusions, aimed at the chosen slice of the original audience. Omit scheduled_at to leave it as a draft. The source campaign's lists are deliberately not carried over — the engagement segment is the audience.

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
audience
required
string
Enum: "non_openers" "openers" "clickers"
subject
string <= 191 characters

Optional new subject line; defaults to the original's

title
string <= 191 characters

Optional internal name; defaults to "Resend: "

scheduled_at
string <date-time>

Optional send time; omit to leave the resend as a draft

Responses

Request samples

Content type
application/json
{
  • "audience": "non_openers",
  • "subject": "string",
  • "title": "string",
  • "scheduled_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "subject": "string",
  • "preview_text": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Lists

List contact lists

Authorizations:
oauth2
query Parameters
query
string

Search query for filtering lists

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Create a new contact list

Authorizations:
oauth2
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "user_id": 0,
  • "average_email_open_percent": 0,
  • "average_email_click_percent": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a specific contact list

Returns list details including average open and click rates

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "user_id": 0,
  • "average_email_open_percent": 0,
  • "average_email_click_percent": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a contact list

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
name
required
string <= 191 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "user_id": 0,
  • "average_email_open_percent": 0,
  • "average_email_click_percent": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a contact list

Soft-deletes a list. Returns 409 if the list is used by forms, landing pages, or automations.

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Get contacts in a list

Authorizations:
oauth2
path Parameters
list_id
required
integer
query Parameters
query
string

Search query for filtering contacts

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Add a contact to a list

Adds an existing contact to a list. If the contact is already in the list, no duplicate is created.

Authorizations:
oauth2
path Parameters
list_id
required
integer
Request Body schema: application/json
contact_id
required
integer

ID of the contact to add

Responses

Request samples

Content type
application/json
{
  • "contact_id": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove a contact from a list

Authorizations:
oauth2
path Parameters
list_id
required
integer
contact_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "email": "[email protected]",
  • "first_name": "string",
  • "last_name": "string",
  • "ip_address": "string",
  • "unsubscribed_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Forms

List forms

Authorizations:
oauth2
query Parameters
query
string

Search query for filtering forms

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Create a new form

Creates a subscription form linked to one or more lists. Free users are limited to 1 form.

Authorizations:
oauth2
Request Body schema: application/json
title
required
string <= 191 characters
lists
required
Array of integers

Array of list IDs to attach

redirect_url
string or null <uri>

URL to redirect to after subscription

gdpr_required
boolean

Whether GDPR consent checkbox is required

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "landing_page_id": 0,
  • "redirect_url": "string",
  • "gdpr_required": true,
  • "url": "string",
  • "lists": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a specific form

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "landing_page_id": 0,
  • "redirect_url": "string",
  • "gdpr_required": true,
  • "url": "string",
  • "lists": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a form

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
title
string <= 191 characters
lists
Array of integers

Replaces all list assignments

redirect_url
string or null <uri>
gdpr_required
boolean

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": 0,
  • "title": "string",
  • "landing_page_id": 0,
  • "redirect_url": "string",
  • "gdpr_required": true,
  • "url": "string",
  • "lists": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a form

Soft-deletes the form

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Automations

List automations

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Create an automation

Authorizations:
oauth2
Request Body schema: application/json
title
required
string
trigger_type
string
Enum: "apply_list" "open_campaign" "click_campaign"
trigger_list_id
integer

Required when trigger_type is apply_list

trigger_campaign_id
integer

Required when trigger_type is open_campaign or click_campaign

active
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "trigger_type": "apply_list",
  • "trigger_list_id": 0,
  • "trigger_campaign_id": 0,
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "user_id": 0,
  • "title": "string",
  • "active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "automation_triggers": [
    ],
  • "automation_items": [
    ]
}

Get a specific automation

Returns automation with triggers, items, and campaign stats

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "user_id": 0,
  • "title": "string",
  • "active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "automation_triggers": [
    ],
  • "automation_items": [
    ]
}

Update an automation

Update title, trigger, or active status. Activating reschedules stale deliverables.

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
title
string
active
boolean
trigger_type
string
Enum: "apply_list" "open_campaign" "click_campaign"
trigger_list_id
integer
trigger_campaign_id
integer

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "active": true,
  • "trigger_type": "apply_list",
  • "trigger_list_id": 0,
  • "trigger_campaign_id": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "user_id": 0,
  • "title": "string",
  • "active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "automation_triggers": [
    ],
  • "automation_items": [
    ]
}

Delete an automation

Soft-deletes the automation and cancels all scheduled deliverables

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Add an email to an automation

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
subject
required
string
html
required
string
from_name
required
string
from_email
required
string <email>
delay_hours
integer [ 0 .. 5000 ]

Hours to wait before sending (default 24, first email defaults to 0)

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "delay_hours": 5000
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "automation_id": 0,
  • "campaign_id": 0,
  • "delay_hours": 0,
  • "send_order": 0,
  • "campaign": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an automation email

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
subject
string
html
string
from_name
string
from_email
string <email>
delay_hours
integer [ 0 .. 5000 ]
send_order
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "subject": "string",
  • "html": "string",
  • "from_name": "string",
  • "from_email": "[email protected]",
  • "delay_hours": 5000,
  • "send_order": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "automation_id": 0,
  • "campaign_id": 0,
  • "delay_hours": 0,
  • "send_order": 0,
  • "campaign": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Remove an email from an automation

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Domains

List sender domains

Returns a paginated list of the user's whitelabel/sender domains

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Add a sender domain

Adds a new sender domain and creates the corresponding SendGrid whitelabel domain. Requires an active subscription and SendGrid subuser.

Authorizations:
oauth2
Request Body schema: application/json
domain
required
string <= 191 characters

Domain name (e.g., example.com). Do not include @ or protocol.

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "domain": "string",
  • "sendgrid_whitelabel_domain_id": 0,
  • "validated_at": "2019-08-24T14:15:22Z",
  • "dns": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get domain with DNS records

Returns domain details including DNS records needed for verification

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "domain": "string",
  • "sendgrid_whitelabel_domain_id": 0,
  • "validated_at": "2019-08-24T14:15:22Z",
  • "dns": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a sender domain

Removes the domain from SendGrid and soft-deletes locally

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Validate domain DNS records

Triggers DNS validation for the domain via SendGrid. Returns whether validation passed and any errors for specific DNS records.

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "valid": true,
  • "domain": {
    }
}

Users

Get current user information

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "email": "[email protected]",
  • "contacts_count": 0,
  • "contact_limit": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Contact Fields

List user contact fields

Returns custom contact fields defined by the user (20 per page)

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "current_page": 0,
  • "total": 0,
  • "per_page": 0
}

Create a custom contact field

Creates a custom field for contacts. The name is auto-generated from the label as a slug. Valid field type IDs: text, number, date (use the UUID constants from the contact_field_types table).

Authorizations:
oauth2
Request Body schema: application/json
label
required
string <= 191 characters

Human-readable field label

contact_field_type_id
required
string

UUID of the field type (text, number, or date)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "contact_field_type_id": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "label": "string",
  • "name": "string",
  • "type": "text"
}

Get a specific contact field

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "label": "string",
  • "name": "string",
  • "type": "text"
}

Update a contact field label

Updates the label and auto-regenerates the name slug. Note: contact_field_type_id is immutable and cannot be changed after creation.

Authorizations:
oauth2
path Parameters
id
required
integer
Request Body schema: application/json
label
required
string <= 191 characters

Responses

Request samples

Content type
application/json
{
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "label": "string",
  • "name": "string",
  • "type": "text"
}

Delete a contact field

Permanently deletes the contact field

Authorizations:
oauth2
path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}