SSpiderIQ
Get Started
SSpiderIQ
Get Started

Docs / api-reference/mail-outreach

Mail Outreach

13 endpoints from the published OpenAPI import.

GET/api/v1/brands/{brand_id}/mail/outreach/connections

List Outreach Connections

List every outreach sidecar for this brand, newest first.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}

Get Outreach Connection

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
PATCH/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}

Update Outreach Connection

Edit workspace_id / warmup_tag / lemwarm_domains / is_active.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X PATCH 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "workspace_id": "string",
  "warmup_tag": "string",
  "lemwarm_domains": [
    "string"
  ],
  "is_active": true,
  "smartlead_client_id": "string",
  "max_active_leads": 0
}'
Python
import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"workspace_id": "string", "warmup_tag": "string", "lemwarm_domains": ["string"], "is_active": true, "smartlead_client_id": "string", "max_active_leads": 0},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"workspace_id": "string", "warmup_tag": "string", "lemwarm_domains": ["string"], "is_active": true, "smartlead_client_id": "string", "max_active_leads": 0})
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"workspace_id": "string", "warmup_tag": "string", "lemwarm_domains": ["string"], "is_active": true, "smartlead_client_id": "string", "max_active_leads": 0}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
DELETE/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}

Delete Outreach Connection

Remove the outreach sidecar. Leaves api_integrations intact (user must delete the integration itself via IntegrationsTab to remove credentials). FK cascades senders + campaigns + health_snapshots on this sidecar.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X DELETE 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.delete(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", {
  method: "DELETE",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
POST/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/sync

Sync Outreach Connection

Call adapter.list_senders(), upsert into mail_outreach_senders, and try to resolve each sender's email against mail_mailboxes for this brand's clients (so the classifier can key off mailbox_id).

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/sync' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/sync",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/sync", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/sync", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/senders

List Outreach Senders

All senders across every outreach connection on this brand.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/senders/{sender_id}/health

Get Sender Health

Time-series for a single sender's health card.

days bounds the history returned (default 30 — matches the Slice F detail chart). The most-recent snapshot is duplicated into latest so the client doesn't have to index into history[0].

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
sender_idpathintegertrue
daysqueryintegerfalse
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders/{sender_id}/health' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders/{sender_id}/health",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders/{sender_id}/health", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/senders/{sender_id}/health", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/warmup-trend

Get Warmup Trend

Per-brand daily warmup/deliverability time-series (#26/#32).

Buckets the brand's snapshots by UTC day, summing the 24h send/inbox counters and averaging the health score. Feeds the outreach Warmup chart AND the security 30-day trend. Hits idx_health_snapshots_brand_polled via the (brands_id, polled_at) range; date_trunc is in SELECT/GROUP BY only, so the index range scan on polled_at is preserved.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
daysqueryintegerfalseTrailing window in days.
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/warmup-trend' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/warmup-trend",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/warmup-trend", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/warmup-trend", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/health/overview

Get Health Overview

Brand outreach overview envelope: the per-sender grid plus brand-level deltas (#23) and quota (#24).

senders is the latest snapshot per sender (one row per sender — powers the HealthCards grid, hits idx_health_snapshots_sender_polled via DISTINCT ON). deltas is this-7d vs prior-7d; quota is 30d send volume vs the plan cap.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/health/overview' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/health/overview",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/health/overview", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/health/overview", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/campaigns

List Remote Campaigns

Campaigns visible to this connection — powers the 'pick a campaign' picker.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/campaigns' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/campaigns",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/campaigns", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/campaigns", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
GET/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push-status

Get Push Status

Quota usage + per-campaign push counts for this connection.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push-status' \
  -H 'Authorization: Bearer <token>'
Python
import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push-status",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push-status", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push-status", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
POST/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push

Push Campaign Leads

Push a SpiderIQ campaign's verified leads into the chosen remote campaign.

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "spideriq_campaign_id": "string",
  "remote_campaign_id": "string",
  "smartlead_campaign_name": "string",
  "limit": 0,
  "only_with_vayapin_seo": false,
  "only_with_vayapin_pin": false
}'
Python
import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"spideriq_campaign_id": "string", "remote_campaign_id": "string", "smartlead_campaign_name": "string", "limit": 0, "only_with_vayapin_seo": false, "only_with_vayapin_pin": false},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"spideriq_campaign_id": "string", "remote_campaign_id": "string", "smartlead_campaign_name": "string", "limit": 0, "only_with_vayapin_seo": false, "only_with_vayapin_pin": false})
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"spideriq_campaign_id": "string", "remote_campaign_id": "string", "smartlead_campaign_name": "string", "limit": 0, "only_with_vayapin_seo": false, "only_with_vayapin_pin": false}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/push", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error
POST/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/remove

Remove Campaign Leads

Remove tracked leads from a remote campaign (frees account lead credits).

Parameters

NameInTypeRequiredDescription
brand_idpathintegertrue
connection_idpathintegertrue
Try it
Query

Examples

cURL
curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/remove' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "remote_campaign_id": "string",
  "spideriq_campaign_id": "string",
  "emails": [
    "string"
  ]
}'
Python
import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/remove",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"remote_campaign_id": "string", "spideriq_campaign_id": "string", "emails": ["string"]},
)
resp.raise_for_status()
print(resp.json())
JavaScript
const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/remove", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"remote_campaign_id": "string", "spideriq_campaign_id": "string", "emails": ["string"]})
});
const data = await resp.json();
console.log(data);
Go
package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"remote_campaign_id": "string", "spideriq_campaign_id": "string", "emails": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/mail/outreach/connections/{connection_id}/remove", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

StatusDescription
200Successful Response
422Validation Error