@apollo-deploy/signal-sdk
v0.0.2
Published
TypeScript SDK for Apollo Signal API
Readme
Apollo Signal API SDK
This SDK was automatically generated by Tesseract.
Installation
npm install @apollo-deploy/signal-sdkQuick Start
import { createApolloSignalApiClient } from '@apollo-deploy/signal-sdk';
const client = createApolloSignalApiClient({
baseUrl: 'https://signal.apollodeploy.com',
});
const api = client.suppressions;Request Options
import { createApolloSignalApiClient } from '@apollo-deploy/signal-sdk';
const client = createApolloSignalApiClient();
const result = await client.suppressions.addSuppression(
/* params */,
{
timeoutMs: 30_000,
headers: {
'X-Trace-Id': 'trace_123',
},
},
);API Reference
SuppressionsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| addSuppression | POST | /signal/projects/${projectId}/suppressions | Adds an email address to the project suppression list. Suppressed addresses will not receive any sends from this project. The reason field records why the address was suppressed (e.g. manual, bounce, complaint). |
| removeSuppression | DELETE | /signal/projects/${projectId}/suppressions/${email} | Removes an email address from the project suppression list, allowing future sends to that address. The email address must be URL-encoded in the path. |
| listSuppressions | GET | /signal/projects/${projectId}/suppressions | Returns a paginated list of suppressed addresses for the project, ordered by suppression date descending. |
| importSuppressions | POST | /signal/projects/${projectId}/suppressions/import | Bulk-imports a list of suppressed addresses into the project. Addresses that are already suppressed are skipped. Returns a count of newly added suppressions. |
| exportSuppressions | GET | /signal/projects/${projectId}/suppressions/export | Exports the entire suppression list for the project as a CSV file. The response has Content-Type: text/csv and a Content-Disposition: attachment header suitable for file download. Large lists are streamed. |
SegmentsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createSegment | POST | /signal/projects/${projectId}/segments | Creates a new audience segment inside the given project. A segment is a named filter that groups contacts for targeted sends or automations. |
| listSegments | GET | /signal/projects/${projectId}/segments | Returns a paginated list of all segments in the given project, ordered by creation date descending. |
| getSegment | GET | /signal/projects/${projectId}/segments/${segmentId} | Retrieves a single segment by its ID. |
| deleteSegment | DELETE | /signal/projects/${projectId}/segments/${segmentId} | Permanently deletes the segment. Contacts that were members of this segment are not deleted — only their membership is removed. |
| listContactsInSegment | GET | /signal/projects/${projectId}/segments/${segmentId}/contacts | Returns a paginated list of contact IDs that are members of the given segment. |
TopicsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createTopic | POST | /signal/projects/${projectId}/topics | Create a new topic for a project. Topics let you segment your audience and manage subscription preferences by interest or category. |
| listTopics | GET | /signal/projects/${projectId}/topics | Return a paginated list of all topics belonging to a project. |
| getTopic | GET | /signal/projects/${projectId}/topics/${topicId} | Retrieve a single topic by its ID. |
| updateTopic | PATCH | /signal/projects/${projectId}/topics/${topicId} | Update one or more fields on an existing topic. Only the fields you provide are changed — omitted fields are left unchanged. |
| deleteTopic | DELETE | /signal/projects/${projectId}/topics/${topicId} | Permanently delete a topic. Contacts subscribed to this topic will lose their subscription records. |
ContactPropertiesAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createContactProperty | POST | /signal/projects/${projectId}/contact-properties | Defines a new custom property that can be attached to contacts in the given project. Properties have a name, a data type (string, number, boolean, date), and an optional default value. |
| listContactProperties | GET | /signal/projects/${projectId}/contact-properties | Returns a paginated list of all custom properties defined in the project. |
| getContactProperty | GET | /signal/projects/${projectId}/contact-properties/${propertyId} | Retrieves a single custom contact property by its ID. |
| updateContactProperty | PATCH | /signal/projects/${projectId}/contact-properties/${propertyId} | Updates the display name or default value of an existing contact property. The property type cannot be changed after creation. |
| deleteContactProperty | DELETE | /signal/projects/${projectId}/contact-properties/${propertyId} | Permanently deletes a contact property. Any values stored against contacts for this property are also removed. |
ContactsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createContact | POST | /signal/projects/${projectId}/contacts | Creates a new contact in the project. Contacts represent email recipients and can hold custom properties, segment memberships, and topic subscription preferences. If a contact with the same email already exists the request returns 409. |
| listContacts | GET | /signal/projects/${projectId}/contacts | Returns a paginated list of all contacts in the project, ordered by creation date descending. |
| getContact | GET | /signal/projects/${projectId}/contacts/${contactId} | Retrieves a single contact by their ID, including custom properties and suppression status. |
| updateContact | PATCH | /signal/projects/${projectId}/contacts/${contactId} | Updates a contact's profile — name, or custom property values. Email address cannot be changed after creation. Omitted fields are left unchanged. |
| deleteContact | DELETE | /signal/projects/${projectId}/contacts/${contactId} | Permanently deletes the contact and all their associated data including custom property values, segment memberships, and topic subscriptions. |
| addContactToSegment | POST | /signal/projects/${projectId}/contacts/${contactId}/segments | Adds the contact to the specified segment. If the contact is already a member of the segment the request is idempotent and returns 204. |
| listContactSegments | GET | /signal/projects/${projectId}/contacts/${contactId}/segments | Returns the IDs of all segments the contact is currently a member of. |
| removeContactFromSegment | DELETE | /signal/projects/${projectId}/contacts/${contactId}/segments/${segmentId} | Removes the contact from the specified segment. The contact record itself is not affected. |
| getContactTopics | GET | /signal/projects/${projectId}/contacts/${contactId}/topics | Returns the contact's current subscription state for each topic defined in the project. The subscription field is subscribed, unsubscribed, or pending. |
| updateContactTopics | PATCH | /signal/projects/${projectId}/contacts/${contactId}/topics | Sets the contact's subscription state for one or more topics. Only the topics included in the request body are updated; others are left unchanged. Useful for implementing preference centre UIs. |
DedicatedIpsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| listDedicatedIpRegions | GET | /signal/dedicated-ips/regions | Returns the default AWS regions Signal supports for all users, with dedicated IP availability appended per region. Use [dedicatedIpSupported] to filter selectable regions in the dedicated IP UI. |
| listDedicatedIps | GET | /signal/dedicated-ips | Returns dedicated sending IP requests and their lifecycle status for the authenticated organisation. |
| requestDedicatedIps | POST | /signal/dedicated-ips | Requests provisioning of dedicated sending IPs in one or more AWS regions. Pass a single region, several regions, or all supported regions from GET /signal/dedicated-ips/regions. Each region requires its own dedicated IP ($30/mo add-on per region, or included on Enterprise). Regions outside your primary region also require the multi-region entitlement (Pulse+). Omit regions to default to the primary region only. |
| getDedicatedIp | GET | /signal/dedicated-ips/${id} | Returns the status of a dedicated IP request, including the first routed timestamp. |
| decommissionDedicatedIp | POST | /signal/dedicated-ips/${id}/cancel | Starts decommissioning a dedicated IP pool. The row moves to cancelling, then cancelled once the background worker tears down the provider pool. This does not mutate the billing subscription; purchased add-on quantity remains owned by billing reconciliation. |
| listDedicatedIpEvents | GET | /signal/dedicated-ips/${id}/events | Audit log of state transitions for a dedicated IP request. |
| getDedicatedIpWarmupProgress | GET | /signal/dedicated-ips/${id}/warmup | Current warmup stage and recent provider warmup samples. |
WebhooksAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createWebhook | POST | /signal/projects/${projectId}/webhooks | Registers a new webhook endpoint for the project. Signal will POST a signed JSON payload to the given URL whenever any of the subscribed event types occurs. Each delivery is signed with HMAC-SHA256 using the endpoint's secret, which is returned once at creation time and never shown again. |
| listWebhooks | GET | /signal/projects/${projectId}/webhooks | Returns a paginated list of all webhook endpoints registered for the project. |
| getWebhook | GET | /signal/projects/${projectId}/webhooks/${endpointId} | Retrieves a single webhook endpoint by its ID. The signing secret is never included in this response. |
| updateWebhook | PATCH | /signal/projects/${projectId}/webhooks/${endpointId} | Updates the configuration of an existing webhook endpoint. You can change the target URL, subscribed event types, description, or enabled/disabled status. Omitted fields are left unchanged. |
| deleteWebhook | DELETE | /signal/projects/${projectId}/webhooks/${endpointId} | Permanently deletes the webhook endpoint. In-flight deliveries will not be retried after deletion. |
| testWebhook | POST | /signal/projects/${projectId}/webhooks/${endpointId}/test | Sends a synthetic test event to the webhook endpoint and returns the delivery result. Use this to verify the endpoint is reachable and that your server can parse and verify the Signal webhook signature before going live. |
| replayWebhookDelivery | POST | /signal/projects/${projectId}/webhooks/${endpointId}/replay/${deliveryId} | Re-sends a specific previous delivery attempt to the webhook endpoint. Useful for recovering from transient failures or replaying events after a prolonged outage. The replayed payload is identical to the original. |
ProjectsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createProject | POST | /signal/projects | Creates a new Signal project within the authenticated organisation. A project is the top-level container for sending domains, contacts, templates, automations, and email sends. |
| listProjects | GET | /signal/projects | Returns a paginated list of all projects in the authenticated organisation. |
| getProject | GET | /signal/projects/${projectId} | Retrieves a single project by its ID. |
| updateProject | PATCH | /signal/projects/${projectId} | Updates the name or configuration of an existing project. Omitted fields are left unchanged. |
| deleteProject | DELETE | /signal/projects/${projectId} | Permanently deletes the project and all its associated resources — domains, contacts, templates, automations, and send history. This action is irreversible. |
| setTrackingDomain | PUT | /signal/projects/${projectId}/tracking-domain | Assigns a custom tracking domain to the project. The domain is used for open and click tracking pixel URLs, replacing the default Signal tracking domain. The domain must be a verified subdomain (e.g. track.yourdomain.com) pointing to Signal's tracking infrastructure via a CNAME record. |
| verifyTrackingDomain | POST | /signal/projects/${projectId}/tracking-domain/verify | Triggers an on-demand DNS verification check for the project's custom tracking domain. Signal checks that the expected CNAME record resolves correctly. The tracking domain status transitions to verified on success. |
| listEmails | GET | /signal/projects/${projectId}/emails | Returns a paginated list of all emails sent from the project, ordered by send date descending. Includes delivery status for each message. |
| getProjectEmail | GET | /signal/projects/${projectId}/emails/${emailId} | Retrieves full email detail including headers, delivery status, and recipient information for an email sent within the project. |
| getEmailTimeline | GET | /signal/projects/${projectId}/emails/${emailId}/events | Returns the full chronological event timeline for a single email — queued, sent, delivered, opened, clicked, bounced, etc. — with ISO 8601 timestamps and associated metadata (e.g. bounce reason, click URL). |
SendingDomainsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| registerDomain | POST | /signal/projects/${projectId}/domains | Registers a new sending domain for the project. Signal generates the required DNS records (SPF, DKIM, DMARC) that must be added to your DNS provider before the domain can be used for sending. The domain enters pending status until verified. |
| listDomains | GET | /signal/projects/${projectId}/domains | Returns a paginated list of all sending domains registered for the project. |
| getDomain | GET | /signal/projects/${projectId}/domains/${domainId} | Retrieves a single registered domain by its ID, including current DNS record statuses and verification state. |
| verifyDomain | POST | /signal/projects/${projectId}/domains/${domainId}/verify | Triggers an on-demand DNS verification check for the domain. Signal queries your DNS provider for the expected SPF, DKIM, and DMARC records. Returns the updated verification status for each record. If all records are present and valid the domain status transitions to verified. |
| deleteDomain | DELETE | /signal/projects/${projectId}/domains/${domainId} | Permanently removes the domain from the project. Verified domains that are actively used for sending should be decommissioned carefully — in-flight messages referencing this domain will not be affected. |
| verifyBimi | POST | /signal/projects/${projectId}/domains/${domainId}/bimi/verify | Triggers a DNS lookup to verify that the domain's BIMI (Brand Indicators for Message Identification) record is correctly published. A valid BIMI record allows supported email clients to display the brand logo in the inbox. |
| updateBimi | PATCH | /signal/projects/${projectId}/domains/${domainId}/bimi | Updates the BIMI configuration for the domain, including the SVG logo URL and optional Verified Mark Certificate (VMC) URL. Changes take effect immediately but DNS propagation may take up to 48 hours. |
EmailsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| sendEmail | POST | /v1/emails | Sends a transactional email immediately or at a scheduled time. You can provide the HTML or plain-text body inline, or reference a saved template with optional variable substitutions. The from address must belong to a verified sending domain in the project.
Emails are delivered through Amazon SES. Delivery status events (delivered, bounced, complained, opened, clicked) are available via webhooks and the email timeline endpoint. |
| getEmail | GET | /v1/emails/${emailId} | Retrieves the full details of a previously sent email by its ID, including the message headers, delivery status, and recipient information. |
| batchSendEmails | POST | /v1/emails/batch | Sends up to 100 emails in a single API call. Each message in the batch is independent and can have a different recipient, subject, and body. Messages are queued atomically — either all are accepted or none are. |
| cancelEmail | DELETE | /v1/emails/${emailId} | Cancels a scheduled email before it is sent. Only emails with status: scheduled can be cancelled. Attempting to cancel an already-sent email returns 409. |
| bulkCancelEmails | DELETE | /v1/emails | Cancels all emails for the project that are currently in scheduled status. Useful for aborting a bulk campaign before delivery begins. |
| issueStreamToken | POST | /v1/emails/stream/token | Issues a short-lived token that authorises a client to connect to the SSE stream at /v1/emails/stream. The token expires after 60 seconds. |
| streamEmailEvents | GET | /v1/emails/stream | Opens a Server-Sent Events (SSE) stream that pushes real-time delivery events for the project. Authenticate via the short-lived token from POST /v1/emails/stream/token. The stream emits: sent, delivered, bounced, complained, opened, clicked, and unsubscribed events. Each payload is a JSON object with emailId, type, and timestamp. |
| scoreSubject | POST | /v1/emails/score-subject | Analyses one or more candidate subject lines and returns a deliverability and engagement score for each. The scorer checks for spam-trigger words, excessive punctuation, emoji density, length, and personalisation signals. |
| validateLinks | POST | /v1/emails/validate | Parses the submitted HTML email body and checks every hyperlink for reachability and common deliverability issues (tracking redirects, link shorteners, HTTP links). Returns a per-link status report with warnings and errors. |
DeliverabilityAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| getDeliverabilityMetrics | GET | /signal/projects/${projectId}/deliverability/summary | Returns aggregated send, delivery, bounce, complaint, and open counts for the project over the requested time window. Useful for high-level dashboard metrics. |
| getDeliverabilityTimeline | GET | /signal/projects/${projectId}/deliverability/timeline | Returns time-series deliverability data broken into granular buckets (hourly or daily) across the requested window. Use this to render trend charts in the dashboard. |
| getDeliverabilityAdvisor | GET | /signal/projects/${projectId}/deliverability/advisor | Runs the deliverability advisor engine against the project's recent send data and returns a scored list of actionable recommendations. Each recommendation has a severity (info, warning, critical) and a structured data payload with context-specific details. |
AutomationsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createAutomation | POST | /signal/projects/${projectId}/automations | Creates a new email automation workflow. An automation consists of a trigger (e.g. event-based or scheduled), an audience filter, and a sequence of steps. The automation starts in draft status and must be activated separately. |
| listAutomations | GET | /signal/projects/${projectId}/automations | Returns a paginated list of automations in the project. Use the status query parameter to filter by lifecycle state. |
| getAutomation | GET | /signal/projects/${projectId}/automations/${automationId} | Retrieves a single automation with its full step configuration and current runtime status. |
| updateAutomation | PATCH | /signal/projects/${projectId}/automations/${automationId} | Updates an existing automation's configuration. Can be used to rename the automation, change its steps, or activate/deactivate it. Only draft automations can have their steps modified. |
| stopAutomation | POST | /signal/projects/${projectId}/automations/${automationId}/stop | Immediately stops an active automation. In-flight runs complete normally but no new runs will be initiated. The automation transitions to stopped status and can be reactivated via the update endpoint. |
| deleteAutomation | DELETE | /signal/projects/${projectId}/automations/${automationId} | Permanently deletes the automation and all associated run history. Active automations must be stopped before deletion. |
| listAutomationRuns | GET | /signal/projects/${projectId}/automations/${automationId}/runs | Returns a paginated list of execution runs for the automation, ordered by start time descending. Each run represents a single contact's journey through the automation steps. |
| getAutomationRun | GET | /signal/projects/${projectId}/automations/${automationId}/runs/${runId} | Retrieves the full detail of a single automation run, including per-step execution status, timing, and any error messages. |
EventsAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| listEvents | GET | /signal/projects/${projectId}/events | Returns a paginated list of all custom event schemas defined in the project. Events can be used to trigger automations. |
| createEvent | POST | /signal/projects/${projectId}/events | Defines a new custom event schema for the project. The schema specifies the event name and its expected properties, which are used to validate incoming event payloads sent via the /send endpoint. |
| sendEvent | POST | /signal/projects/${projectId}/events/send | Fires a custom event for a specific contact. Matching active automations that are triggered by this event type will immediately start a new run for the contact. The event payload is validated against the registered schema. |
| getEvent | GET | /signal/projects/${projectId}/events/${id} | Retrieves a single event schema by its ID. |
| updateEvent | PATCH | /signal/projects/${projectId}/events/${id} | Updates the schema definition of an existing custom event. Property additions are backward-compatible; removing or renaming properties may break existing automation triggers. |
| deleteEvent | DELETE | /signal/projects/${projectId}/events/${id} | Permanently deletes the event schema. Active automations that reference this event type will stop triggering but are not automatically deactivated. |
TemplatesAPI
| Method | HTTP | Path | Description |
|--------|------|------|-------------|
| createTemplate | POST | /signal/projects/${projectId}/templates | Creates a new email template in the project. Templates support HTML and plain-text content with Handlebars-style variable substitution. A new version (v1) is created automatically. |
| listTemplates | GET | /signal/projects/${projectId}/templates | Returns a paginated list of templates in the project. Archived templates are excluded unless a filter is applied. |
| getTemplate | GET | /signal/projects/${projectId}/templates/${templateId} | Retrieves a single template by ID, including its latest version's content. |
| updateTemplate | PATCH | /signal/projects/${projectId}/templates/${templateId} | Updates an existing template. Saving changes creates a new version, preserving the full edit history. Omitted fields are left unchanged. |
| archiveTemplate | DELETE | /signal/projects/${projectId}/templates/${templateId} | Archives the template, hiding it from the default list view. Archived templates cannot be used in new sends but their history is retained. Archiving is reversible via the update endpoint. |
| duplicateTemplate | POST | /signal/projects/${projectId}/templates/${templateId}/duplicate | Creates a copy of an existing template, optionally with a new name. The duplicate starts at version 1 with the current content of the source template. |
| listTemplateVersions | GET | /signal/projects/${projectId}/templates/${templateId}/versions | Returns a paginated version history for the template, ordered by version number descending. Each version captures the full content at the time of the save. |
Types
AddSuppressionBodySuppressionResponseSuppressionImportRowSerializableSuppressionImportBodyCreateSegmentBodySegmentResponseCreateTopicBodyTopicResponseUpdateTopicBodyCreateContactPropertyBodyContactPropertyResponseUpdateContactPropertyBodySegmentRefTopicSubscriptionBodyCreateContactBodyContactResponseUpdateContactBodyAddToSegmentBodyUpdateTopicsBodyUsageAggregateItemUsageAggregateResponseQuotaEntryUsageQuotasFeatureFlagsEntitlementsResultSignalRegionResponseDedicatedIpRegionCatalogResponseRequestDedicatedIpBodyDedicatedIpResponseRequestDedicatedIpResponseWarmupSampleResponseWarmupProgressResponseWebhookFilterSerializableWebhookTransformationSerializableCreateWebhookBodyWebhookCreateResponseWebhookResponseUpdateWebhookBodyWebhookDeliveryResponseCreateProjectRequestProjectLimitsProjectTrackingSettingsProjectResponseUpdateProjectRequestSetTrackingDomainRequestCnameRecordTrackingDomainResponseEmailDetailResponseEmailTimelineItemEmailTimelineResponseRegisterDomainRequestDkimRecordDnsRecordVerificationRecordsDomainResponseUpdateBimiRequestAttachmentRequestDeliveryWindowRequestTrackingSettingsRequestSendEmailRequestSendEmailResponseBatchSendRequestBatchSendItemResponseBatchSendResponseCancelResponseBulkCancelResponseStreamTokenResponseScoreSubjectRequestSubjectScoreItemScoreSubjectResponseValidateLinksRequestLinkResultItemValidateLinksResponseHealthCheckResultCreateImportJobResponseImportResourceProgressResponseImportJobErrorResponseImportJobProgressResponseImportJobStreamTokenResponseDeliverabilityWindowResponseDeliverabilityCountResponseDeliverabilityCountSummaryResponseDeliverabilityTimelineBucketResponseDeliverabilityTimelineResponseDeliverabilityAdvisorRecommendationResponseDeliverabilityAdvisorResponseStepRequestConnectionRequestCreateAutomationRequestAutomationCreatedResponseAutomationResponseAutomationListResponseStepResponseConnectionResponseAutomationDetailResponseUpdateAutomationRequestAutomationStoppedResponseAutomationDeletedResponseAutomationRunResponseAutomationRunListResponseRunStepResponseAutomationRunDetailResponseEventResponseEventListResponseCreateEventRequestEventCreatedResponseSendEventRequestSendEventResponseUpdateEventSchemaRequestEventUpdatedResponseEventDeletedResponseCreateTemplateRequestTemplateResponseTemplateVersionResponseTemplateWithVersionResponseUpdateTemplateRequestDuplicateTemplateRequestDmarcIngestResponseDmarcReportSummaryDmarcListResponse
Error Handling
import { SDKError } from '@apollo-deploy/signal-sdk';
try {
const result = await client.someApi.someMethod();
} catch (error) {
if (error instanceof SDKError) {
console.error(`Error ${error.status}: ${error.message} (${error.code})`);
}
}