Sequences

Sequences are automated multi-step email campaigns. Use these endpoints to list sequences, control their execution, and manage enrolled contacts.

List Sequences

GET /sequences

Returns all sequences with optional status filter and pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 200)
`status`	string	—	Filter by status (`drafted`, `live`, `paused`, `completed`)

curl "https://api.graph8.com/api/v1/sequences?status=live" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/sequences",
    headers=HEADERS,
    params={"status": "live"}
)

Response

{
  "data": [
    {
      "id": "seq-abc",
      "name": "Q2 Outbound",
      "status": "live",
      "user_email": "rep@company.com",
      "associated_list_id": 5,
      "created_at": "2026-02-15T10:00:00",
      "updated_at": "2026-02-20T14:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "has_next": false
  }
}

Get Sequence

GET /sequences/{sequence_id}

Returns detailed information about a sequence, including configuration flags.

Example

cURL
Python

curl "https://api.graph8.com/api/v1/sequences/seq-abc" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/sequences/seq-abc",
    headers=HEADERS
)

Response

{
  "data": {
    "id": "seq-abc",
    "name": "Q2 Outbound",
    "description": "Multi-touch outbound campaign for Q2 targets",
    "status": "live",
    "user_email": "rep@company.com",
    "associated_list_id": 5,
    "finish_on_reply": true,
    "send_in_same_thread": false,
    "wait_for_new_contacts": false,
    "paused_at": null,
    "resumed_at": null,
    "created_at": "2026-02-15T10:00:00",
    "updated_at": "2026-02-20T14:30:00"
  }
}

Run Sequence

POST /sequences/{sequence_id}/run

Start a drafted sequence. Generates scheduling events for all enrolled contacts.

Example

cURL
Python

curl -X POST "https://api.graph8.com/api/v1/sequences/seq-abc/run" \
  -H "Authorization: Bearer $API_KEY"

response = requests.post(
    f"{BASE_URL}/sequences/seq-abc/run",
    headers=HEADERS
)

Response

{
  "data": {
    "sequence_id": "seq-abc",
    "status": "scheduling",
    "contacts_affected": 150
  }
}

Pause Sequence

POST /sequences/{sequence_id}/pause

Pause a live sequence. Scheduled sends are held until the sequence is resumed.

Response

{
  "data": {
    "sequence_id": "seq-abc",
    "status": "paused",
    "contacts_affected": 150
  }
}

Resume Sequence

POST /sequences/{sequence_id}/resume

Resume a paused sequence. Held sends are rescheduled.

Response

{
  "data": {
    "sequence_id": "seq-abc",
    "status": "live",
    "contacts_affected": 150
  }
}

List Sequence Contacts

GET /sequences/{sequence_id}/contacts

Returns contacts enrolled in a sequence with their current state.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 200)
`state`	string	—	Filter by contact state

Example

cURL
Python

curl "https://api.graph8.com/api/v1/sequences/seq-abc/contacts?state=active" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/sequences/seq-abc/contacts",
    headers=HEADERS,
    params={"state": "active"}
)

Response

{
  "data": [
    {
      "id": "sc-1",
      "contact_id": 12345,
      "state": "active",
      "current_step_order": 2,
      "created_at": "2026-02-15T10:00:00",
      "updated_at": "2026-02-18T09:00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "has_next": false
  }
}

Add Contacts to Sequence

POST /sequences/{sequence_id}/contacts

Add contacts to a live or drafted sequence. Returns 201 Created.

Request Body

Field	Type	Required	Description
`contact_ids`	integer[]	Yes	Contact IDs to add
`list_id`	integer	Yes	List ID the contacts belong to

Example

cURL
Python

curl -X POST "https://api.graph8.com/api/v1/sequences/seq-abc/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": [101, 102, 103], "list_id": 5}'

response = requests.post(
    f"{BASE_URL}/sequences/seq-abc/contacts",
    headers=HEADERS,
    json={"contact_ids": [101, 102, 103], "list_id": 5}
)

Response

{
  "data": {
    "sequence_id": "seq-abc",
    "status": "contacts_added",
    "contacts_affected": 3
  }
}