Skip to content

feat(emails): add POST /emails/schedule for programmatic campaign creation #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
brayanjeshua wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(emails): add POST /emails/schedule for programmatic campaign creation #310

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
272 changes: 272 additions & 0 deletions apps/emails.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
"in": "query",
"description": "Filter by schedule status",
"schema": {
"default": "active",

Check warning on line 46 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Unknown Property 

Details:
OpenAPI v3.0 specifications contain properties not recognized by the standard
schema, indicating potential typos, deprecated fields, or custom extensions.
Unknown properties may cause validation failures or unexpected API behavior.
Review and remove unrecognized fields or properly namespace custom extensions
using 'x-' prefix.

Recommendation:
The field 'default' is known in the parameters object
"enum": [
"active",
"pause",
Expand Down Expand Up @@ -223,14 +223,98 @@
},
"security": [
{
"Location-Access": [

Check warning on line 226 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Security Requirement Object With Wrong Scopes 

Details:
OpenAPI security requirements define scopes for authentication schemes, but only
OAuth2 and OpenID Connect support scope-based authorization. Specifying scopes
for API Key or HTTP authentication types creates invalid configurations that fail
validation. Remove scopes from security requirements using authentication types
that do not support them.

Recommendation:
'security.Location-Access' has no scopes defined for security scheme of type
'http'
"emails/schedule.readonly"
]
}
],
"tags": [

Check warning on line 231 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Campaigns"
]
},
"post": {
"operationId": "create-email-campaign",
"summary": "Create or Schedule an Email Campaign",
"description": "Creates a new email campaign as a draft or schedules it to send at a specific date and time. Supports `draft`, `send_now`, and `schedule_later` campaign types. The HTML content can be provided directly or referenced via a template built with `POST /emails/builder`.",
"parameters": [
{
"name": "Version",
"in": "header",
"description": "API Version",
"required": true,
"schema": {
"type": "string",
"enum": [
"2021-07-28"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateScheduleDto"
}
}
}
},
"responses": {
"201": {
"description": "Campaign created or scheduled successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateScheduleSuccessfulResponseDto"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "../common/common-schemas.json#/components/schemas/BadRequestDTO"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "../common/common-schemas.json#/components/schemas/UnauthorizedDTO"
}
}
}
},
"404": {
"description": "Not Found"
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "../common/common-schemas.json#/components/schemas/UnprocessableDTO"
}
}
}
}
},
"security": [
{
"Location-Access": [

Check warning on line 310 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Security Requirement Object With Wrong Scopes 

Details:
OpenAPI security requirements define scopes for authentication schemes, but only
OAuth2 and OpenID Connect support scope-based authorization. Specifying scopes
for API Key or HTTP authentication types creates invalid configurations that fail
validation. Remove scopes from security requirements using authentication types
that do not support them.

Recommendation:
'security.Location-Access' has no scopes defined for security scheme of type
'http'
"emails/schedule.write"
]
}
],
"tags": [

Check warning on line 315 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Email Marketing"
]
}
},
"/emails/builder": {
Expand Down Expand Up @@ -309,12 +393,12 @@
},
"security": [
{
"Location-Access": [

Check warning on line 396 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Security Requirement Object With Wrong Scopes 

Details:
OpenAPI security requirements define scopes for authentication schemes, but only
OAuth2 and OpenID Connect support scope-based authorization. Specifying scopes
for API Key or HTTP authentication types creates invalid configurations that fail
validation. Remove scopes from security requirements using authentication types
that do not support them.

Recommendation:
'security.Location-Access' has no scopes defined for security scheme of type
'http'
"emails/builder.write"
]
}
],
"tags": [

Check warning on line 401 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Templates"
]
},
Expand All @@ -337,7 +421,7 @@
"required": false,
"in": "query",
"schema": {
"default": 10,

Check warning on line 424 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Default Invalid 

Details:
Schema objects with 'default' values that don't match their defined type create
validation inconsistencies and may cause unexpected API behavior. Ensure default
values align with the schema's declared type.

Recommendation:
The field 'default' should be consistent with the type
"type": "string"
}
},
Expand Down Expand Up @@ -486,12 +570,12 @@
},
"security": [
{
"Location-Access": [

Check warning on line 573 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Security Requirement Object With Wrong Scopes 

Details:
OpenAPI security requirements define scopes for authentication schemes, but only
OAuth2 and OpenID Connect support scope-based authorization. Specifying scopes
for API Key or HTTP authentication types creates invalid configurations that fail
validation. Remove scopes from security requirements using authentication types
that do not support them.

Recommendation:
'security.Location-Access' has no scopes defined for security scheme of type
'http'
"emails/builder.readonly"
]
}
],
"tags": [

Check warning on line 578 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Templates"
]
}
Expand All @@ -503,7 +587,7 @@
"description": "Delete a template",
"parameters": [
{
"name": "locationId",

Check warning on line 590 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Template Path With No Corresponding Path Parameter 

Details:
OpenAPI path templates containing parameters (e.g., `/users/{userId}`) must
define corresponding path parameters in operation objects with 'in' set to
'path'. Missing parameter definitions break API contracts and cause runtime
errors when consumers attempt invalid requests. Define all templated path
parameters in operation parameter lists.

Recommendation:
Template path parameter should have an operation parameter with the same name and
'in' set to 'path'
"required": true,
"in": "path",
"example": "ve9EPM428h8vShlRW1KT",
Expand All @@ -512,7 +596,7 @@
}
},
{
"name": "templateId",

Check warning on line 599 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Template Path With No Corresponding Path Parameter 

Details:
OpenAPI path templates containing parameters (e.g., `/users/{userId}`) must
define corresponding path parameters in operation objects with 'in' set to
'path'. Missing parameter definitions break API contracts and cause runtime
errors when consumers attempt invalid requests. Define all templated path
parameters in operation parameter lists.

Recommendation:
Template path parameter should have an operation parameter with the same name and
'in' set to 'path'
"required": true,
"in": "path",
"example": "zYy3YOUuHxgomU1uYJty",
Expand All @@ -521,7 +605,7 @@
}
},
{
"name": "Version",

Check warning on line 608 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Template Path With No Corresponding Path Parameter 

Details:
OpenAPI path templates containing parameters (e.g., `/users/{userId}`) must
define corresponding path parameters in operation objects with 'in' set to
'path'. Missing parameter definitions break API contracts and cause runtime
errors when consumers attempt invalid requests. Define all templated path
parameters in operation parameter lists.

Recommendation:
Template path parameter should have an operation parameter with the same name and
'in' set to 'path'
"in": "header",
"description": "API Version",
"required": true,
Expand Down Expand Up @@ -583,7 +667,7 @@
"Location-Access": []
}
],
"tags": [

Check warning on line 670 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Templates"
]
}
Expand Down Expand Up @@ -664,12 +748,12 @@
},
"security": [
{
"Location-Access": [

Check warning on line 751 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Security Requirement Object With Wrong Scopes 

Details:
OpenAPI security requirements define scopes for authentication schemes, but only
OAuth2 and OpenID Connect support scope-based authorization. Specifying scopes
for API Key or HTTP authentication types creates invalid configurations that fail
validation. Remove scopes from security requirements using authentication types
that do not support them.

Recommendation:
'security.Location-Access' has no scopes defined for security scheme of type
'http'
"emails/builder.write"
]
}
],
"tags": [

Check warning on line 756 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Templates"
]
}
Expand Down Expand Up @@ -714,7 +798,7 @@
"description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
"type": "http"
},
"Location-Access": {

Check warning on line 801 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Components Object Fixed Field Key Improperly Named 

Details:
Component object field keys in OpenAPI specifications must follow naming
conventions allowing only alphanumeric characters, periods, hyphens, and
underscores. Non-compliant keys cause parsing errors and break tooling
compatibility. Use keys matching the pattern `^[a-zA-Z0-9\.\-_]+$`.

Recommendation:
components.{{securitySchemes}}.{{Location-Access}} is properly named
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
Expand All @@ -722,7 +806,7 @@
"description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.",
"type": "http"
},
"Agency-Access": {

Check warning on line 809 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Components Object Fixed Field Key Improperly Named 

Details:
Component object field keys in OpenAPI specifications must follow naming
conventions allowing only alphanumeric characters, periods, hyphens, and
underscores. Non-compliant keys cause parsing errors and break tooling
compatibility. Use keys matching the pattern `^[a-zA-Z0-9\.\-_]+$`.

Recommendation:
components.{{securitySchemes}}.{{Agency-Access}} is properly named
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
Expand All @@ -730,7 +814,7 @@
"description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.",
"type": "http"
},
"Location-Access-Only": {

Check warning on line 817 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Components Object Fixed Field Key Improperly Named 

Details:
Component object field keys in OpenAPI specifications must follow naming
conventions allowing only alphanumeric characters, periods, hyphens, and
underscores. Non-compliant keys cause parsing errors and break tooling
compatibility. Use keys matching the pattern `^[a-zA-Z0-9\.\-_]+$`.

Recommendation:
components.{{securitySchemes}}.{{Location-Access-Only}} is properly named
"scheme": "bearer",
"bearerFormat": "JWT",
"name": "Authorization",
Expand Down Expand Up @@ -1178,12 +1262,200 @@
"description": "template data download url"
}
}
},
"CreateScheduleDto": {
"type": "object",
"properties": {
"locationId": {
"type": "string",
"description": "The GHL location (sub-account) ID",
"example": "8Nua7uN3cDjUVlpiK9D0"
},
"name": {
"type": "string",
"description": "Internal name for the campaign",
"example": "My Email Campaign"
},
"subject": {
"type": "string",
"description": "Email subject line shown in the recipient's inbox",
"example": "We'd love to connect with you"
},
"from": {
"type": "string",
"description": "Sender email address (must be a verified sending domain)",
"example": "info@yourdomain.com"
},
"fromName": {
"type": "string",
"description": "Sender display name",
"example": "Your Company"
},
"html": {
"type": "string",
"description": "Full HTML content of the email body. Either `html` or `templateId` must be provided."
},
"templateId": {
"type": "string",
"description": "ID of an existing Email Builder template (from `POST /emails/builder`). Used instead of `html` when referencing a saved template.",
"example": "6a526c938708da5288f5c149"
},
"campaignType": {
"type": "string",
"description": "Determines when or how the campaign is sent.",
"enum": [
"draft",
"send_now",
"schedule_later"
],
"example": "schedule_later"
},
"status": {
"type": "string",
"description": "Initial campaign status. Use `draft` to save without sending.",
"enum": [
"draft",
"scheduled",
"active"
],
"example": "scheduled"
},
"dateScheduled": {
"type": "number",
"description": "Unix timestamp in **milliseconds** (UTC) for when the campaign should be sent. Required when `campaignType` is `schedule_later`.",
"example": 1752487200000
},
"sendDays": {
"type": "array",
"description": "Days of the week on which sending is allowed (for throttled or drip campaigns).",
"items": {
"type": "string",
"enum": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri",
"Sat",
"Sun"
]
},
"example": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
]
},
"hasTracking": {
"type": "boolean",
"description": "Enable open and click tracking",
"example": true
},
"hasUtmTracking": {
"type": "boolean",
"description": "Append UTM parameters to all links in the email",
"example": true
},
"enableResendToUnopened": {
"type": "boolean",
"description": "Automatically resend the campaign to contacts who did not open the first send",
"example": false
},
"resendInfo": {
"type": "object",
"description": "Configuration for the resend-to-unopened flow. Required when `enableResendToUnopened` is true.",
"properties": {
"resendSubject": {
"type": "string",
"description": "Alternative subject line for the resend",
"example": "Did you see this?"
},
"resendDuration": {
"type": "object",
"description": "How long to wait before resending",
"properties": {
"hours": {
"type": "number",
"example": 24
},
"days": {
"type": "number",
"example": 0
},
"minutes": {
"type": "number",
"example": 0
}
}
}
}
}
},
"required": [
"locationId",
"name",
"subject",
"campaignType"
]
},
"CreateScheduleSuccessfulResponseDto": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique campaign ID",
"example": "6a3021409784277ce6f523e5"
},
"name": {
"type": "string",
"example": "My Email Campaign"
},
"subject": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"draft",
"scheduled",
"active"
],
"example": "scheduled"
},
"campaignType": {
"type": "string",
"enum": [
"draft",
"send_now",
"schedule_later"
],
"example": "schedule_later"
},
"locationId": {
"type": "string"
},
"dateScheduled": {
"type": "number",
"description": "Scheduled send time as Unix ms timestamp",
"example": 1752487200000
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
}
},
"x-tagGroups": {
"name": "Email",
"tags": [

Check warning on line 1458 in apps/emails.json

View check run for this annotation

Orca Security (US) / Orca Security - Infrastructure as Code

[INFO] Object Without Required Property 

Details:
OpenAPI v3 specification objects lack required fields defined by the standard,
causing schema validation failures and potential client integration issues.
Missing required properties prevent proper API documentation parsing and code
generation. Include all mandatory fields as specified in the OpenAPI 3.0
specification.

Recommendation:
tags has all required fields
"Emails",
"Campaigns",
"Templates",
Expand Down