PageHub Emails API
The emails a site sends, and the address they come from.
The emails a site sends, and the address they come from.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pagehub-dev:pagehub-dev-emails-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: PageHub Emails API
version: 1.0.0
description: 'The public REST API of PageHub, called with a `ph_` API key (`Authorization: Bearer ph_...`), plus the one webhook the platform calls on a white-label tenant''s server (`fetchPage`).
A site is HTML + Liquid files: its pages are files (`pages/*.liquid`), written through the files API; the page routes manage each page''s record (name, slug, SEO, access). Writes land in the site''s draft; `PUT /api/v1/sites/{id}` with `published: true` makes the draft live.
The headless content API (`/api/v1/content/...`) is described by its own document (`GET /api/v1/content/openapi.json`); `GET /api/openapi.json` serves this document with it merged in.
The routes also accept the dashboard''s session cookie from the dashboard itself; only the API key is the public contract.
Every operation carries two extension fields. `x-auth` says who may call it: `api-key` (a `ph_` key), `session-or-key` (the dashboard''s own session, or a key), `optional-key` (public, a key widens what you see), `admin-key` (a platform admin''s key), `session` (the dashboard session only; an API key is refused) or `public`. `x-rate-limit` names the rate-limit rule (see the rate-limiting guide) when the route has one; most routes limit per user, public routes per IP.'
contact:
name: PageHub
url: https://pagehub.dev/developers
servers:
- url: https://pagehub.dev
description: PageHub
security:
- bearerAuth: []
tags:
- name: Emails
description: The emails a site sends, and the address they come from.
paths:
/api/v1/sites/{id}/emails:
get:
tags:
- Emails
summary: List the site's emails
description: Every email kind, whether the owner customized it, and whether it is sent today.
operationId: listSiteEmails
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
kind:
$ref: '#/components/schemas/SiteEmailKind'
group:
type: string
name:
type: string
description:
type: string
customized:
type: boolean
enabled:
type: boolean
reason:
type: string
required:
- kind
- name
- customized
- enabled
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/emails/brand:
get:
tags:
- Emails
summary: Read the look of the site's emails
operationId: getSiteEmailBrand
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailBrandView'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
put:
tags:
- Emails
summary: Change the look of the site's emails
description: Logo on or off and the button colour, on every plan.
operationId: putSiteEmailBrand
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
brand:
type: object
properties:
showLogo:
type: boolean
buttonColor:
type: string
enum:
- primary
- secondary
- accent
- neutral
required:
- showLogo
- buttonColor
required:
- brand
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailBrandView'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/emails/{kind}:
get:
tags:
- Emails
summary: Read one email
description: The stored design (null = default) with file versions, the defaults, the kind's variables and slots, sample data, and `feature.customDesigns` (whether the owner's plan saves custom designs).
operationId: getSiteEmail
parameters:
- $ref: '#/components/parameters/SiteId'
- $ref: '#/components/parameters/EmailKind'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
html:
type:
- boolean
- string
- 'null'
subject:
type:
- string
- 'null'
preheader:
type:
- string
- 'null'
source:
type:
- string
- 'null'
versions:
type: object
additionalProperties: true
defaults:
type: object
properties:
subject:
type: string
preheader:
type: string
source:
type: string
variables:
type: array
items:
type: object
additionalProperties: true
slots:
type: array
items:
type: object
additionalProperties: true
sample:
type: object
additionalProperties: true
theme:
type:
- object
- 'null'
properties:
text:
type: string
version:
type: string
image:
type: string
feature:
type: object
properties:
customDesigns:
type: boolean
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
put:
tags:
- Emails
summary: Save one email
description: '`source` (the design) needs a plan with custom designs and an HTML-first site; `subject` and `preheader` save on every plan. The design is checked before saving; problems come back as `errors`. `base` carries the file versions the edit started from.'
operationId: putSiteEmail
parameters:
- $ref: '#/components/parameters/SiteId'
- $ref: '#/components/parameters/EmailKind'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
subject:
type:
- string
- 'null'
preheader:
type:
- string
- 'null'
source:
type:
- string
- 'null'
base:
type: object
properties:
source:
type: string
meta:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
errors:
type: array
items:
type: object
additionalProperties: true
warnings:
type: array
items:
type: object
additionalProperties: true
required:
- ok
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: A conflict (`error` says which).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'413':
description: The request or file is too large.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
$ref: '#/components/responses/WriteRejected'
'503':
$ref: '#/components/responses/Maintenance'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
delete:
tags:
- Emails
summary: Reset one email to the default
description: Both of the email's files are removed.
operationId: resetSiteEmail
parameters:
- $ref: '#/components/parameters/SiteId'
- $ref: '#/components/parameters/EmailKind'
responses:
'200':
$ref: '#/components/responses/Ok'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'503':
$ref: '#/components/responses/Maintenance'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/emails/{kind}/preview:
post:
tags:
- Emails
summary: Preview an unsaved email
description: Renders the draft with sample data. A field the body leaves out uses what is saved. A design with errors renders the default (`usedDefault`).
operationId: previewSiteEmail
parameters:
- $ref: '#/components/parameters/SiteId'
- $ref: '#/components/parameters/EmailKind'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/EmailDraft'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EmailPreview'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/emails/{kind}/test:
post:
tags:
- Emails
summary: Send a test of an unsaved email
description: 'Sends the draft, with sample data, to the signed-in user only. Dashboard session only: an API key is refused. Refused while the design has errors.'
operationId: testSiteEmail
parameters:
- $ref: '#/components/parameters/SiteId'
- $ref: '#/components/parameters/EmailKind'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/EmailDraft'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
to:
type: string
required:
- ok
- to
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'502':
description: An upstream service (Stripe, Vercel, a mail server, a stock provider) failed or refused.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'503':
$ref: '#/components/responses/Maintenance'
x-auth: session
x-rate-limit: dashboard_settings_save
security: []
/api/v1/sites/{id}/email-sender:
get:
tags:
- Emails
summary: Read the address the site's emails come from
description: How mail goes out now, the saved SMTP settings (password masked), the last error, and what PageHub sending looks like for this site.
operationId: getSiteEmailSender
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MailSender'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
put:
tags:
- Emails
summary: Save the site's own mail server
description: 'Owner or agency role, on a plan with own sender. Saved unverified: nothing changes until the test succeeds. Without `password`, the stored one is kept only if host, port and username are unchanged.'
operationId: putSiteEmailSender
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fromName:
type: string
fromEmail:
type: string
replyTo:
type: string
host:
type: string
port:
type: integer
description: One of the allowed SMTP ports (587 for most servers).
user:
type: string
password:
type: string
maxLength: 512
required:
- fromEmail
- host
- port
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MailSender'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
delete:
tags:
- Emails
summary: Remove the site's own mail server
description: Back to PageHub sending. Open on every plan.
operationId: deleteSiteEmailSender
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MailSender'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/email-sender/test:
post:
tags:
- Emails
summary: Test the site's mail server
description: Connects, logs in, and sends one email to the signed-in user from the owner's address. Success turns the sender on. Dashboard session only; owner or agency role.
operationId: testSiteEmailSender
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
to:
type: string
required:
- ok
- to
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: A conflict (`error` says which).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
$ref: '#/components/responses/RateLimited'
'502':
description: An upstream service (Stripe, Vercel, a mail server, a stock provider) failed or refused.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
x-auth: session
x-rate-limit: dashboard_settings_save
security: []
components:
schemas:
SiteEmailKind:
type: string
enum:
- order_receipt
- subscription_welcome
- order_shipped
- booking_confirmed
- booking_requested
- booking_declined
- gift_card_gifted
- gift_card_self
- customer_login
- download_delivery
- download_update
MailSender:
type: object
properties:
mode:
type: string
enum:
- pagehub
- smtp
fromName:
type: string
fromEmail:
type: string
replyTo:
type: string
smtp:
type:
- object
- 'null'
properties:
host:
type: string
port:
type: integer
userMasked:
type: string
hasPassword:
type: boolean
verifiedAt:
type:
- string
- 'null'
format: date-time
lastError:
type: string
lastErrorAt:
type:
- string
- 'null'
format: date-time
consecutiveFailures:
type: integer
pagehub:
type: object
properties:
from:
type: string
replyTo:
type:
- string
- 'null'
feature:
type: object
properties:
enabled:
type: boolean
required:
- mode
- pagehub
- feature
EmailBrandView:
type: object
properties:
brand:
type: object
properties:
showLogo:
type: boolean
buttonColor:
type: string
enum:
- primary
- secondary
- accent
- neutral
required:
- showLogo
- buttonColor
swatches:
type: object
additionalProperties:
type: string
description: The site theme's real colour (`#hex`) for each button token.
required:
- brand
- swatches
EmailDraft:
type: object
properties:
subject:
type:
- string
- 'null'
preheader:
type:
- string
- 'null'
source:
type:
- string
- 'null'
description: The email's Liquid design; `null` or empty resets it to the default.
ApiError:
type: object
description: The error body of the management routes. The content API uses `Error` instead.
properties:
error:
type: string
description: A message, or a code such as `version_conflict`, `lint`, `maintenance`, `site_format_changed`.
message:
type: string
code:
type: string
upgrade:
type: boolean
description: True when the plan is the reason.
required:
- error
additionalProperties: true
EmailPreview:
type: object
properties:
subject:
type: string
html:
type: string
text:
type: string
errors:
type: array
items:
type: object
additionalProperties: true
warnings:
type: array
items:
type: object
additionalProperties: true
usedDefault:
type: boolean
required:
- subject
- html
- text
additionalProperties: true
parameters:
SiteId:
name: id
in: path
required: true
schema:
type: string
description: The site's id.
EmailKind:
name: kind
in: path
required: true
schema:
$ref: '#/components/schemas/SiteEmailKind'
description: Which email.
responses:
Unauthorized:
description: Missing, malformed or invalid `ph_` API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Ok:
description: OK
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
required:
- ok
BadRequest:
description: The request is malformed or refused (`error`, often `message`).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
WriteRejected:
description: 'A file write was refused: `lint` (422, with `issues` and `path`), too large (413), or another `rejected` reason.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
NotFound:
description: No such site, or the key has no access to it, or no such resource under it.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Forbidden:
description: The key's user lacks the role this needs, or a plan limit applies.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
RateLimited:
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Maintenance:
description: 'Writes are paused for maintenance (`error: maintenance`, `Retry-After` header).'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A `ph_` API key (a user's key, or a tenant's).
tenantAuthToken:
type: apiKey
in: header
name: x-pagehub-auth
description: The tenant's token, sent by PageHub on every webhook call so the tenant can check the request came from PageHub.