Help us shape the future of Go! Take the 2026 Go Developer Survey

external

package
v0.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: AGPL-3.0 Imports: 49 Imported by: 0

Documentation

Overview

Package external implements the /api surface: the public API, authenticated by a Workspace's bearer API token.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditLog

type AuditLog interface {
	Licensed() bool
	// Entries returns up to limit entries, newest first, preceding the cursor entry
	// id (0 = from the newest), and the next page's cursor (0 = last page).
	Entries(ctx context.Context, s *ent.Scoped, f events.AuditFilter, cursor int64, limit int) ([]*ent.AuditEntry, int64, error)
}

AuditLog is the read seam of the Enterprise Audit log (ADR 0022), implemented by ee/audit. Core knows only this interface: without a license Licensed is false and the read answers 402.

type Deps

type Deps struct {
	Accounts     *accounts.Accounts
	Bus          *events.Bus
	Webhooks     *webhooks.Module
	Integrations *integrations.Module
	// CapturedMessages is the store of what the Workspace's Test inbox kept.
	CapturedMessages *capturedmessages.Module
	SendingDomains   *sendingdomains.Module
	Outbound         *outbound.Module
	Segments         *segments.Module
	EventLog         *eventlog.Module
	Contacts         *contacts.Module
	Erasure          *erasure.Module
	Tags             *tags.Module
	Templates        *templates.Module
	Transactional    *transactional.Module
	BrandKit         *brandkit.Module
	Automations      *automations.Module
	Rules            *rules.Module
	Broadcasts       *broadcasts.Module
	Reputation       *reputation.Module
	BootstrapToken   string
	Audit            AuditLog
	Export           ExportStreams
}

Deps is everything the /api handlers are built from. The domain modules are the shared singletons the composition root registers once, so /api and /site cannot diverge on how a module is constructed.

type ExportStreams

type ExportStreams interface {
	Licensed() bool
}

ExportStreams is the license seam of the Enterprise Export streams (ADR 0045), implemented by ee/export. Core serves the streams itself (internal/exportstream) and asks only whether the `export` feature is licensed: without it every stream answers 404.

type Handlers

type Handlers struct {
	externalapi.UnimplementedHandler
	// contains filtered or unexported fields
}

func NewHandlers

func NewHandlers(d Deps) *Handlers

func (*Handlers) AuditEntriesList

AuditEntriesList reads the Workspace's Audit log, newest first, for a token with the audit:read scope (a SIEM feed). An instance without an Enterprise license answers 402 (ADR 0014, ADR 0022).

func (*Handlers) AuthMeGet

func (h *Handlers) AuthMeGet(ctx context.Context) (externalapi.AuthMeGetRes, error)

func (*Handlers) AuthTokensList

func (h *Handlers) AuthTokensList(ctx context.Context) (externalapi.AuthTokensListRes, error)

func (*Handlers) AutomationsActivate

AutomationsActivate and AutomationsDeactivate need automations:activate, which authoring scopes never imply (ADR 0016). Over MCP, activate additionally needs mcp:send (the x-mcp send flag).

func (*Handlers) AutomationsArchive

AutomationsArchive archives an automation (ADR 0049); active enrollments refuse it with 409.

func (*Handlers) AutomationsCreate

AutomationsCreate always stores a draft: activating is the send-class operation.

func (*Handlers) AutomationsDryRunHttpStep

AutomationsDryRunHttpStep renders an HTTP step's body for a Contact and validates it; nothing is called. It reads a Contact, so it needs both scopes.

func (*Handlers) AutomationsGet

func (*Handlers) AutomationsList

func (*Handlers) AutomationsUnarchive

AutomationsUnarchive restores an archived automation.

func (*Handlers) BrandKitGet

func (h *Handlers) BrandKitGet(ctx context.Context) (externalapi.BrandKitGetRes, error)

BrandKitGet returns the Workspace's Brand kit for an agent to write a message in (ADR 0040). It needs only the right to read Templates; the Brand kit is never written over /api.

func (*Handlers) BroadcastsArchive

BroadcastsArchive archives a sent or failed broadcast (ADR 0049).

func (*Handlers) BroadcastsGet

func (*Handlers) BroadcastsList

func (*Handlers) BroadcastsSchedule

BroadcastsSchedule and BroadcastsUnschedule are send-class (ADR 0016, "Send is a second lock"): they need broadcasts:send, which authoring scopes never imply. Over MCP they additionally need mcp:send (the x-mcp send flag).

func (*Handlers) BroadcastsTestSend

BroadcastsTestSend renders the broadcast with sample merge data and sends it to one address: no recipient rows, no tracking, never the audience.

func (*Handlers) BroadcastsUnarchive

BroadcastsUnarchive restores an archived broadcast.

func (*Handlers) CapturedMessagesDelete

CapturedMessagesDelete deletes one Captured message.

func (*Handlers) CapturedMessagesDeleteAll

func (h *Handlers) CapturedMessagesDeleteAll(ctx context.Context) (externalapi.CapturedMessagesDeleteAllRes, error)

CapturedMessagesDeleteAll deletes every Captured message of the Workspace.

func (*Handlers) CapturedMessagesGet

CapturedMessagesGet returns one Captured message in full.

func (*Handlers) CapturedMessagesList

CapturedMessagesList returns the Workspace's Captured messages, newest first, without content.

func (*Handlers) ContactsBatchUpsert

ContactsBatchUpsert upserts each Contact independently and reports a per-item result.

func (*Handlers) ContactsCreate

func (*Handlers) ContactsDelete

ContactsDelete is Erasure (ADR 0021): deleting a Contact removes its personal data. It has its own scope, separate from contacts:write, because it is irreversible.

func (*Handlers) ContactsEraseBy

ContactsEraseBy is Erasure by an email address or a visitor id (ADR 0021), under the same scope and rules as deleting by id. Exactly one identifier is required.

func (*Handlers) ContactsExport

ContactsExport streams the subject-access Data export of one contact (ADR 0021), needing only the contact read scope.

func (*Handlers) ContactsGet

func (*Handlers) ContactsList

func (*Handlers) CustomFieldsList

func (h *Handlers) CustomFieldsList(ctx context.Context) (externalapi.CustomFieldsListRes, error)

CustomFieldsList returns the whole (small, unpaginated) Custom field catalogue.

func (*Handlers) EmailLintLint

EmailLintLint lints a message without saving it (ADR 0040): the one lint of the save paths and the send planner, with the Workspace's Brand kit. What cannot render is an error; everything else is a warning. It needs only the right to read Templates, as it stores nothing.

func (*Handlers) EmailSchemaGet

func (h *Handlers) EmailSchemaGet(ctx context.Context) (externalapi.EmailSchemaGetRes, error)

EmailSchemaGet describes the editor's document to an agent (ADR 0040): the structure the editor derives, with the attribute rules the server checks. It holds no Workspace data and needs only the right to read Templates.

func (*Handlers) EmailsSend

EmailsSend is the transactional send surface (ADR 0005). The whole operation is the transactional module's; this handler only unpacks the request, calls it and renders its Result as the HTTP contract. The optional Idempotency-Key becomes the send's claim key: a repeated key replays the recorded outcome instead of sending again, and a key whose first request is still in flight returns 409.

func (*Handlers) EnrollmentsGet

func (*Handlers) EnrollmentsList

func (*Handlers) EventsBatchSubmit

EventsBatchSubmit records each Event independently and reports a per-item result.

func (*Handlers) EventsCreate

func (*Handlers) ExportAudit

ExportAudit serves the Audit stream (ADR 0045): the Audit entries oldest first as NDJSON. It needs the `audit` license feature as well as `export`; without it the operation is absent (404), like the Audit log read is without its license.

func (*Handlers) ExportContacts

ExportContacts serves the Contacts stream (ADR 0045), the same shape as ExportEvents.

func (*Handlers) ExportErasures

ExportErasures serves the Erasures stream (ADR 0045): NDJSON rows, the next cursor in the X-Next-Cursor header, behind the same gate as every Export stream.

func (*Handlers) ExportEvents

ExportEvents serves the Events stream (ADR 0045): NDJSON rows, the next cursor in the X-Next-Cursor header. A stream added later is this handler with its own typed responses and its own exportstream page function.

func (*Handlers) ExportMessages

ExportMessages serves the Outbound messages stream (ADR 0045): the same NDJSON page, cursor header and gates as the Events stream, over delivery metadata only.

func (*Handlers) IntegrationsArchive

IntegrationsArchive archives an Integration (ADR 0049): it leaves the list and gives up the default, unless live work uses it (409).

func (*Handlers) IntegrationsCreate

IntegrationsCreate stores a new Integration; credentials are sealed and never returned.

func (*Handlers) IntegrationsGet

IntegrationsGet returns one Integration with secrets redacted.

func (*Handlers) IntegrationsList

IntegrationsList returns the Workspace's sending-provider Integrations with the Send rate limit as enforced and the last 24 hours of usage.

func (*Handlers) IntegrationsRegenerateKey

IntegrationsRegenerateKey gives the Integration a new hook key: the old hook URL stops working at once. Hidden from MCP, because it breaks a working URL and needs a person.

func (*Handlers) IntegrationsUnarchive

IntegrationsUnarchive restores an archived Integration to the list. It is not the default.

func (*Handlers) IntegrationsUpdate

IntegrationsUpdate edits an Integration. Omitting config keeps the stored credentials; blank secret fields inside a supplied config keep the stored secret.

func (*Handlers) PresetsList

func (h *Handlers) PresetsList(ctx context.Context) (externalapi.PresetsListRes, error)

PresetsList returns the Presets the Instance offers with the params schema of each: how an agent learns what an Integration's `params` takes.

func (*Handlers) RuleFiringsList

RuleFiringsList lists a Rule's Firings, newest first.

func (*Handlers) RulesActivate

RulesActivate and RulesDeactivate need automations:activate, which authoring scopes never imply (ADR 0016). Over MCP, activate additionally needs mcp:send (the x-mcp send flag).

func (*Handlers) RulesArchive

RulesArchive archives a Rule (ADR 0049): it acts on nothing and keeps its Firings.

func (*Handlers) RulesCreate

RulesCreate always stores a draft: activating is the send-class operation.

func (*Handlers) RulesDeactivate

func (*Handlers) RulesDelete

RulesDelete purges a Rule that has no Firings; one with Firings is archived instead (409).

func (*Handlers) RulesDryRun

RulesDryRun reports what a stored Event would do to the Rule. It writes and runs nothing, so reading scope is enough.

func (*Handlers) RulesGet

func (*Handlers) RulesList

func (*Handlers) RulesUnarchive

RulesUnarchive restores an archived Rule, as a draft.

func (*Handlers) SegmentsArchive

SegmentsArchive archives a segment (ADR 0049); a draft or scheduled Broadcast refuses it with 409.

func (*Handlers) SegmentsCreate

func (*Handlers) SegmentsGet

func (*Handlers) SegmentsList

func (*Handlers) SegmentsUnarchive

SegmentsUnarchive restores an archived segment to the list.

func (*Handlers) SendingDomainRatesList

SendingDomainRatesList returns the (numerator, denominator, rate) triples of ADR 0011 for every Sending domain, over the trailing window.

func (*Handlers) SendingDomainsArchive

SendingDomainsArchive archives a Sending domain (ADR 0049): it leaves the list and serves no Tracking domain host. Live sends from it refuse it with 409.

func (*Handlers) SendingDomainsCreate

SendingDomainsCreate adds a Sending domain; the DKIM keypair is minted and sealed.

func (*Handlers) SendingDomainsGet

SendingDomainsGet returns one Sending domain.

func (*Handlers) SendingDomainsList

SendingDomainsList returns the Workspace's Sending domains with the DNS records to publish.

func (*Handlers) SendingDomainsUnarchive

SendingDomainsUnarchive restores an archived Sending domain and starts a DNS check.

func (*Handlers) SendingDomainsUpdate

SendingDomainsUpdate changes the DKIM selector, which unverifies the domain.

func (*Handlers) SendingDomainsVerify

SendingDomainsVerify triggers the live DKIM check and returns the domain as it stands; the outcome shows on a later read (`verified`, `lastCheckedAt`).

func (*Handlers) TagsDelete

TagsDelete deletes a Tag from the catalogue unless a Segment rule or an Automation step names it (ADR 0049).

func (*Handlers) TagsList

func (*Handlers) TagsRemove

func (*Handlers) TemplatesDelete

func (*Handlers) TemplatesGet

func (*Handlers) TemplatesList

func (*Handlers) WebhooksCreate

func (*Handlers) WebhooksDelete

func (*Handlers) WebhooksGet

func (*Handlers) WebhooksList

func (*Handlers) WebhooksRegenerateSecret

WebhooksRegenerateSecret replaces the endpoint's signing secret. The new secret is not part of the response: the external API never returns it.

func (*Handlers) WebhooksTest

WebhooksTest sends a sample event to the endpoint and returns what the receiver answered; the endpoint's failure state is not touched.

Directories

Path Synopsis
Package resources holds goverter-generated mappers from ent entities to external API resources, plus the custom conversions goverter cannot infer.
Package resources holds goverter-generated mappers from ent entities to external API resources, plus the custom conversions goverter cannot infer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL