Postconditions: what we check

• sendEmail · api-error

  error
  WhenAny HTTP or network failure: invalid API token (401 InvalidAPIKeyError), validation error (422 ApiInputError — invalid sender, missing fields), inactive recipients (422/406 InactiveRecipientsError), rate limit exceeded (429 RateLimitExceededError), server error (500 InternalServerError), service unavailable (503 ServiceUnavailablerError), or network/DNS failure.
  ThrowsInvalidAPIKeyError (401 — bad server token), ApiInputError (422 — validation failures), InactiveRecipientsError (422/406 — bounced recipients, extends ApiInputError), InvalidEmailRequestError (422/300 — malformed email request, extends ApiInputError), RateLimitExceededError (429 — too many requests), InternalServerError (500 — Postmark server error), ServiceUnavailablerError (503 — Postmark unavailable), UnknownError (other HTTP status codes). All extend PostmarkError with code and statusCode properties.
  Required handlingCaller MUST wrap client.sendEmail() in try-catch. Email delivery failures must be detected — users expect confirmation emails, receipts, and notifications to arrive. Unhandled rejection crashes the process. Minimum handling: try { await client.sendEmail({ From, To, Subject, TextBody }); } catch (error) { if (error instanceof Errors.InactiveRecipientsError) { // Handle bounced recipient } console.error('Email send failed:', error.message); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• sendEmailBatch · api-error

  error
  WhenAny HTTP or network failure: authentication, validation, rate limit, server error, or network failure. Partial batch failures may occur where some emails succeed and others fail within the response.
  ThrowsSame error hierarchy as sendEmail. InvalidAPIKeyError (401), ApiInputError (422), RateLimitExceededError (429), InternalServerError (500), ServiceUnavailablerError (503).
  Required handlingCaller MUST wrap client.sendEmailBatch() in try-catch. Batch email failures affect multiple recipients simultaneously. try { const results = await client.sendEmailBatch(messages); } catch (error) { console.error('Batch send failed:', error.message); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• sendEmailWithTemplate · api-error

  error
  WhenAny HTTP or network failure: authentication, template not found, validation error (missing template model variables), rate limit, server error, or network failure.
  ThrowsSame error hierarchy as sendEmail. Additionally, ApiInputError (422) is thrown when TemplateId/TemplateAlias is invalid or required TemplateModel variables are missing.
  Required handlingCaller MUST wrap client.sendEmailWithTemplate() in try-catch. try { await client.sendEmailWithTemplate({ TemplateAlias: 'welcome', TemplateModel: { name: user.name }, From: 'hello@example.com', To: user.email, }); } catch (error) { console.error('Template email failed:', error.message); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][4]
• sendEmailBatchWithTemplates · api-error

  error
  WhenAny HTTP or network failure: authentication, template not found, validation error, rate limit, server error, or network failure.
  ThrowsSame error hierarchy as sendEmail and sendEmailWithTemplate.
  Required handlingCaller MUST wrap client.sendEmailBatchWithTemplates() in try-catch. try { const results = await client.sendEmailBatchWithTemplates(messages); } catch (error) { console.error('Batch template send failed:', error.message); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][4]
• activateBounce · activate-bounce-no-try-catch

  error
  WhenactivateBounce() called in async context without surrounding try/catch. Throws PostmarkError subclasses on any HTTP or network failure including invalid bounce ID (ApiInputError), revoked token (InvalidAPIKeyError), or bounce not eligible for reactivation (CanActivate: false).
  ThrowsPostmarkError (InvalidAPIKeyError 401, ApiInputError 422, UnknownError)
  Required handlingCaller MUST wrap activateBounce() in try-catch: try { const result = await client.activateBounce(bounceId); // result.Bounce.CanActivate tells you if it worked } catch (error) { if (error instanceof Errors.InvalidAPIKeyError) { // Auth token invalid } console.error('Bounce activation failed:', error.message); }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][2]
• createSuppressions · create-suppressions-no-try-catch

  error
  WhencreateSuppressions() called in async context without surrounding try/catch, OR called without checking per-item Status in the response. The API returns 200 OK with Status: "Failed" for individual addresses on validation or authorization failure — not just on HTTP 4xx/5xx errors.
  ThrowsPostmarkError (InvalidAPIKeyError 401, InactiveRecipientsError 406, RateLimitExceededError 429)
  Required handlingCaller MUST wrap createSuppressions() in try-catch AND check item statuses: try { const result = await client.createSuppressions('outbound', { Suppressions: [{ EmailAddress: email }] }); const failed = result.Suppressions.filter(s => s.Status === 'Failed'); if (failed.length > 0) { console.error('Failed to suppress:', failed.map(s => s.EmailAddress)); } } catch (error) { console.error('Suppression API failed:', error.message); }
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[8][4]
• deleteSuppressions · delete-suppressions-no-try-catch

  error
  WhendeleteSuppressions() called in async context without surrounding try/catch, OR called without checking per-item Status in the response. SpamComplaint suppressions always return Status: "Failed" with HTTP 200 OK — this is not an exception, it is a silent API-level constraint that callers must check.
  ThrowsPostmarkError (InvalidAPIKeyError 401, RateLimitExceededError 429, ServerError 5xx)
  Required handlingCaller MUST wrap deleteSuppressions() in try-catch AND check item statuses: try { const result = await client.deleteSuppressions('outbound', { Suppressions: [{ EmailAddress: email }] }); const failed = result.Suppressions.filter(s => s.Status === 'Failed'); if (failed.length > 0) { // SpamComplaint suppressions cannot be deleted console.warn('Could not remove suppressions:', failed); } } catch (error) { console.error('Delete suppressions failed:', error.message); }
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[8][4]
• createTemplate · create-template-no-try-catch

  error
  WhencreateTemplate() called in async context without surrounding try/catch. Throws ApiInputError (422) for invalid alias format, missing required fields, or 100-template server limit exceeded. Throws InvalidAPIKeyError (401) for bad server token. Throws RateLimitExceededError (429) under high load.
  ThrowsPostmarkError (ApiInputError 422, InvalidAPIKeyError 401, RateLimitExceededError 429)
  Required handlingCaller MUST wrap createTemplate() in try-catch: try { const template = await client.createTemplate({ Name: 'Welcome Email', Subject: 'Welcome to {{product_name}}', HtmlBody: '<p>Hello, {{name}}!</p>', TextBody: 'Hello, {{name}}!', Alias: 'welcome-v1', }); console.log('Template ID:', template.TemplateId); } catch (error) { console.error('Template creation failed:', error.message); // Check if 100-template limit exceeded }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][4]
• editTemplate · edit-template-no-try-catch

  error
  WheneditTemplate() called in async context without surrounding try/catch. Throws ApiInputError (422) when template ID or alias is not found on the server, or when the alias format is invalid. Throws InvalidAPIKeyError (401) for auth failures. Throws RateLimitExceededError (429) and InternalServerError (500) under API failure conditions.
  ThrowsPostmarkError (ApiInputError 422, InvalidAPIKeyError 401, RateLimitExceededError 429)
  Required handlingCaller MUST wrap editTemplate() in try-catch: try { const updated = await client.editTemplate('welcome-v1', { Subject: 'Welcome to {{company_name}}!', HtmlBody: '<p>Hi {{name}}, welcome aboard!</p>', }); console.log('Template updated:', updated.TemplateId); } catch (error) { if (error instanceof Errors.ApiInputError) { console.error('Template not found or validation failed:', error.message); } else { console.error('Template update failed:', error.message); } throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][4]
• deleteTemplate · delete-template-no-try-catch

  error
  WhendeleteTemplate() called in async context without surrounding try/catch. Two distinct destructive-failure paths: (1) template not found — server returns HTTP 404 mapped to a generic PostmarkError (NOT ApiInputError — there is no 404 mapping in errors/ErrorHandler.js, so callers that only catch ApiInputError still crash on missing templates); (2) layout template with dependent standard templates — server returns ErrorCode 1130 on HTTP 422 mapped to ApiInputError ("The layout template cannot be deleted because it has dependent templates using it.").
  ThrowsPostmarkError (404 not-found generic PostmarkError, 422 ApiInputError ErrorCode 1130 layout-cascade, 401 InvalidAPIKeyError, 429 RateLimitExceededError, 500 InternalServerError)
  Required handlingCaller MUST wrap deleteTemplate() in try-catch AND handle both the generic PostmarkError (for 404 not-found) and ApiInputError (for the ErrorCode 1130 layout-cascade case) explicitly. Tear-down scripts must order layout deletion AFTER all dependent standard templates, OR catch the 1130 ApiInputError and re-queue the layout for a second pass: try { const result = await client.deleteTemplate('welcome-v1'); console.log('Deleted:', result.Message); } catch (error) { if (error instanceof Errors.ApiInputError) { // ErrorCode 1130: layout still has dependent standard templates console.error('Layout cascade blocked:', error.message); // Re-queue or delete dependent templates first } else if (error instanceof Errors.PostmarkError) { // 404 template-not-found arrives here (no specialized class) console.warn('Template already absent:', error.message); } else { throw error; } }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][10][11][4]
• createWebhook · create-webhook-no-try-catch

  error
  WhencreateWebhook() called in async context without surrounding try/catch. Throws ApiInputError (422 ErrorCode 606) when the webhook URL is invalid, unreachable, or contains a private/internal IP range (Postmark blocks localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x). Throws InvalidAPIKeyError (401) on auth failure. Throws RateLimitExceededError (429) under load.
  ThrowsPostmarkError (ApiInputError 422 ErrorCode 606 invalid-url, InvalidAPIKeyError 401, RateLimitExceededError 429, InternalServerError 500)
  Required handlingCaller MUST wrap createWebhook() in try-catch. Webhook provisioning code typically runs at server startup or first-install — any thrown error must be caught and surfaced to the operator: try { const webhook = await client.createWebhook({ Url: process.env.WEBHOOK_URL!, HttpAuth: { Username: 'user', Password: process.env.WEBHOOK_SECRET! }, Triggers: { Delivery: { Enabled: true }, Bounce: { Enabled: true, IncludeContent: false }, }, }); console.log('Webhook registered:', webhook.ID); } catch (error) { if (error instanceof Errors.ApiInputError) { // ErrorCode 606: URL invalid or contains internal IP range console.error('Webhook URL rejected by Postmark:', error.message); // Alert ops — email events will not be delivered until resolved } else { console.error('Webhook creation failed:', error.message); } throw error; // Re-throw — startup should fail if webhook not provisioned }
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[12][13][11]
• createMessageStream · create-message-stream-no-try-catch

  error
  WhencreateMessageStream() called in async context without surrounding try/catch. Throws ApiInputError (422) with unique stream-provisioning error codes: 1225 (max 10 streams per server), 1227 (invalid ID format — must be lowercase letters/numbers/hyphens/underscores, start with letter, max 30 chars), 1228 (already have one inbound stream), 1230 (ID already exists), 1233 (ID starts with reserved 'pm-' prefix), 1237 (ID is reserved). These error codes are DISTINCT from sendEmail error codes — callers catching generic PostmarkError still see them but cannot distinguish the provisioning error from a runtime email error without checking the error code.
  ThrowsPostmarkError (ApiInputError 422 ErrorCodes 1221/1223/1224/1225/1227/1228/1230/1233/1237, InvalidAPIKeyError 401, RateLimitExceededError 429, InternalServerError 500)
  Required handlingCaller MUST wrap createMessageStream() in try-catch with error-code checking for the unique stream-provisioning codes. Provisioning scripts that call this at deploy time should surface ALL errors to the operator: try { const stream = await client.createMessageStream({ ID: 'marketing-outbound', Name: 'Marketing Outbound', MessageStreamType: 'Broadcasts', }); console.log('Stream created:', stream.ID); } catch (error) { if (error instanceof Errors.ApiInputError) { const code = (error as any).code; if (code === 1225) { console.error('Max 10 message streams reached — delete unused streams first'); } else if (code === 1227) { console.error('Invalid stream ID format — use lowercase letters/numbers/hyphens only, start with letter, max 30 chars'); } else if (code === 1228) { console.error('Only one inbound stream is allowed per server'); } else if (code === 1230) { console.error('Stream ID already exists — choose a different ID'); } else { console.error('Message stream creation failed:', error.message); } } else { console.error('Stream creation failed:', error.message); } throw error; // Re-throw — all downstream email for this channel will fail }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[14][13][11]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.