Sequences

Read your automated email sequences — list them, read a sequence and its steps' content, set the filters of a step, and pull delivery and engagement stats at both the sequence and individual-step level.

GET/api/v1/sequences

Get a cursor-paginated list of sequences for the authenticated account. Live sequences are returned first, then alphabetically by name. Supports optional query parameters: status (draft, live, paused), search (partial name match), project (numeric project ID — only sequences assigned to that project), per_page (default 25, max 100), and cursor (next/previous page token).

Response Fields

idinteger

The sequence ID.

namestring

The sequence name.

statusstring

The sequence status: draft, live, or paused.

steps_countinteger

Number of steps in the sequence.

contacts_countinteger

Number of enrolled contacts.

Request

curl -X GET \
  "https://byomailer.com/api/v1/sequences" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": [
    {
      "id": 7,
      "name": "Onboarding",
      "status": "live",
      "steps_count": 4,
      "contacts_count": 318
    }
  ],
  "meta": {
    "path": "https://byomailer.com/api/v1/sequences",
    "per_page": 25,
    "next_cursor": "eyJpZCI6N30",
    "prev_cursor": null
  }
}

GET/api/v1/sequences/{sequenceId}

Get a single sequence with the full content of every step (subject, preview text, html and text body, sending identity and template).

Path Parameters

sequenceIdinteger

required

The ID of the sequence to retrieve.

Response Fields

idinteger

The sequence ID.

namestring

The sequence name.

statusstring

The sequence status.

contacts_countinteger

Number of enrolled contacts.

steps_countinteger

Number of steps.

stepsarray

Steps in send order, each with id, delay_days, delay_type, status and message content.

content_variablesobject

Default values for template variables.

filtersarray

Audience filters applied to the sequence.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X GET \
  "https://byomailer.com/api/v1/sequences/{sequenceId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 7,
    "name": "Onboarding",
    "status": "live",
    "contacts_count": 318,
    "steps_count": 4,
    "steps": [
      {
        "id": 31,
        "sequence_id": 7,
        "delay_days": 0,
        "delay_type": "days",
        "status": "live",
        "message": {
          "id": 88,
          "subject": "Welcome aboard",
          "preview_text": "Glad you are here",
          "html_content": "<p>Hi {{ name }}…</p>",
          "text_content": "Hi {{ name }}…",
          "email_identity_id": 3
        },
        "created_at": "2026-06-01T09:00:00.000000Z"
      }
    ],
    "filters": [],
    "content_variables": {
      "name": "there"
    },
    "created_at": "2026-06-01T09:00:00.000000Z"
  }
}

GET/api/v1/sequences/{sequenceId}/stats

Get sequence-level delivery and engagement stats: contact, unsubscribe and click totals plus aggregate mail metrics across all steps. For a per-step breakdown call the step stats endpoint.

Path Parameters

sequenceIdinteger

required

The ID of the sequence to read stats for.

Response Fields

idinteger

The sequence ID.

namestring

The sequence name.

statusstring

The sequence status.

statsobject

Sequence-wide contacts, unsubscribed and clicked totals (distinct contacts).

mail_metricsobject

Aggregate metrics across every step: total, sent, delivered, pending, opened, bounced, unsubscribed, complained and delivery/open/unsubscribe rates.

Request

curl -X GET \
  "https://byomailer.com/api/v1/sequences/{sequenceId}/stats" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 7,
    "name": "Onboarding",
    "status": "live",
    "stats": {
      "contacts": 318,
      "unsubscribed": 6,
      "clicked": 121
    },
    "mail_metrics": {
      "total": 1180,
      "sent": 1180,
      "delivered": 1170,
      "pending": 0,
      "opened": 540,
      "bounced": 10,
      "unsubscribed": 6,
      "complained": 0,
      "delivery_rate": 99.2,
      "open_rate": 45.8,
      "unsubscribe_rate": 0.5
    }
  }
}

GET/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}

Get the full content of a single sequence step.

Path Parameters

sequenceIdinteger

required

The ID of the sequence the step belongs to.

sequenceStepIdinteger

required

The ID of the step to retrieve.

Response Fields

idinteger

The step ID.

sequence_idinteger

The parent sequence ID.

delay_daysinteger

Delay before this step.

delay_typestring

Unit of the delay (e.g. days).

statusstring

The step status.

filtersarray

Step filters. A contact who does not match them skips only this step. Empty when the step has no filters.

messageobject

Step message content: subject, preview_text, html_content, text_content, email identity and template.

created_atstring

ISO 8601 creation timestamp.

Request

curl -X GET \
  "https://byomailer.com/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 31,
    "sequence_id": 7,
    "delay_days": 0,
    "delay_type": "days",
    "status": "live",
    "filters": [],
    "message": {
      "id": 88,
      "subject": "Welcome aboard",
      "preview_text": "Glad you are here",
      "html_content": "<p>Hi {{ name }}…</p>",
      "text_content": "Hi {{ name }}…",
      "email_identity": {
        "id": 3,
        "name": "Acme",
        "email": "[email protected]"
      }
    },
    "created_at": "2026-06-01T09:00:00.000000Z"
  }
}

PATCH/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}/filters

Replace the filters of a single sequence step. A contact who does not match the step filters skips only this email and continues to the next step. The sequence filters still apply first. Works on draft and live steps. Send an empty array to clear the filters. Uses the same filter validation as newsletters. Returns the updated step.

Path Parameters

sequenceIdinteger

required

The ID of the sequence the step belongs to.

sequenceStepIdinteger

required

The ID of the step to update.

Body Parameters

filtersarray

required

Up to 20 filters. See the Filters page for the structure. Send [] to clear.

Request

curl -X PATCH \
  "https://byomailer.com/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}/filters" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": [
    {
      "connector": "and",
      "category": "tags",
      "mode": "any",
      "values": [
        "vip"
      ]
    }
  ]
}'

Response

200

{
  "data": {
    "id": 31,
    "sequence_id": 7,
    "delay_days": 2,
    "delay_type": "days",
    "status": "live",
    "filters": [
      {
        "connector": "and",
        "category": "tags",
        "mode": "any",
        "values": [
          "vip"
        ]
      }
    ],
    "message": {
      "id": 88,
      "subject": "Welcome aboard"
    },
    "created_at": "2026-06-01T09:00:00.000000Z"
  }
}

GET/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}/stats

Get delivery and engagement stats for a single sequence step. Contacts are counted in the furthest step they have reached, so per-step totals do not double-count contacts who have progressed.

Path Parameters

sequenceIdinteger

required

The ID of the sequence the step belongs to.

sequenceStepIdinteger

required

The ID of the step to read stats for.

Response Fields

idinteger

The step ID.

sequence_idinteger

The parent sequence ID.

subjectstring

The step message subject.

delay_daysinteger

Delay before this step.

delay_typestring

Unit of the delay (e.g. days).

statusstring

The step status.

statsobject

Contacts reached, unsubscribed and clicked totals (distinct contacts) for this step.

mail_metricsobject

Step metrics: total, sent, delivered, pending, opened, bounced, unsubscribed, complained and delivery/open/unsubscribe rates.

Request

curl -X GET \
  "https://byomailer.com/api/v1/sequences/{sequenceId}/steps/{sequenceStepId}/stats" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": {
    "id": 31,
    "sequence_id": 7,
    "subject": "Welcome aboard",
    "delay_days": 0,
    "delay_type": "days",
    "status": "live",
    "stats": {
      "contacts": 318,
      "unsubscribed": 2,
      "clicked": 80
    },
    "mail_metrics": {
      "total": 1180,
      "sent": 1180,
      "delivered": 1170,
      "pending": 0,
      "opened": 540,
      "bounced": 10,
      "unsubscribed": 6,
      "complained": 0,
      "delivery_rate": 99.2,
      "open_rate": 45.8,
      "unsubscribe_rate": 0.5
    }
  }
}