Member Junction
    Preparing search index...

    Class SendGridProvider

    Implementation of the SendGrid provider for sending and receiving messages.

    SendGrid is a transactional email service. This provider supports:

    • Sending single messages
    • Sending to multiple recipients (via engine)
    • Inbound email via the SendGrid Inbound Parse Webhook (push notifications):
      • CreateSubscription / DeleteSubscription manage the hostname→URL Inbound Parse mapping via SendGrid's REST API (/v3/user/webhooks/parse/settings).
      • ParseNotification parses the inbound multipart/form-data POST that SendGrid delivers to the consumer's URL. This is INLINE delivery: the POST body contains the ENTIRE parsed email, so NormalizedNotification.Message is populated and there is NO re-fetch (SendGrid has no inbound-retrieval API).

    It does NOT support:

    • Fetching messages (no inbox access / no inbound-retrieval API)
    • Forwarding messages
    • Replying to messages
    • Creating drafts

    SendGrid Inbound Parse is unsigned — there is no cryptographic signature on the inbound POST and no expiry on the registration. Because the message is delivered inline (the payload IS the data path), a forged notification is NOT harmless. Consumers MUST protect the notification endpoint out-of-band: use a hard-to-guess URL secret path and/or network controls (IP allow-listing, private ingress). ParseNotification therefore always returns SignatureValid: undefined (no scheme to verify).

    // Using environment credentials (default)
    await engine.SendSingleMessage('SendGrid', 'Standard Email', message);

    // Using per-request credentials
    await engine.SendSingleMessage('SendGrid', 'Standard Email', message, undefined, false, {
        apiKey: 'SG.customer-specific-key'
    });

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Accessors

    MessageRetrieval ProviderName SupportsPush

    Methods

    ArchiveMessage CreateDraft CreateSubscription DeleteMessage DeleteSubscription DownloadAttachment ForwardMessage GetEvents GetMessages GetSingleMessage GetSubscriptionCapabilities getSupportedOperations ListAttachments ListFolders MarkAsRead MoveMessage ParseNotification RenewSubscription ReplyToMessage SearchMessages SendSingleMessage supportsOperation

    Constructors

    Accessors

    • get MessageRetrieval(): MessageRetrievalCapabilities

      What this provider can narrow on when reading messages. See MessageRetrievalCapabilities.

      Deliberately declares nothing supported. A provider that can push a filter down overrides this and says so; one that has not been updated keeps describing itself accurately instead of promising a filter it silently ignores.

      Returns MessageRetrievalCapabilities

    • get ProviderName(): string

      Returns the name of this provider for use in error messages. Override in subclasses to provide a more descriptive name.

      Returns string

    • get SupportsPush(): boolean

      Convenience gate: true when this provider supports inbound push in ANY form (subscription-managed or inbound-parse), false otherwise. Lets callers cleanly short-circuit — if (provider.SupportsPush) { ... } — instead of probing individual operations.

      Derived from GetSubscriptionCapabilities so it stays in lockstep with actual capability: providers that support push return capabilities and thereby report SupportsPush === true for free; providers that don't return undefined and report false. Subclasses normally do NOT override this — override GetSubscriptionCapabilities instead.

      Returns boolean

    Methods

    • Reads calendar events for one identifier.

      CONCRETE, NOT ABSTRACT, and deliberately so: making it abstract would break every existing provider at compile time for a capability most of them will never have. A provider that supports it overrides this and adds 'GetEvents' to getSupportedOperations(); everything else inherits a refusal that NAMES ITSELF, so a caller learns which provider declined rather than receiving an empty list it cannot distinguish from an empty calendar.

      That distinction is the whole reason this returns Success:false rather than {Events: []}. "This provider cannot look" and "there was nothing in the window" are different facts, and a caller advancing a watermark must not treat the first as the second.

      Parameters

      Returns Promise<GetEventsResult<Record<string, any>>>

    • Parses an inbound SendGrid Inbound Parse notification. PURE: no network calls, and safe on hostile/garbage input — never throws; returns Success: false with a 400 suggested status on malformed payloads.

      The body is multipart/form-data; the boundary is read from the content-type header. The full parsed email is delivered inline, so this populates NormalizedNotification.Message directly (INLINE mode — no re-fetch).

      SignatureValid is always undefined: Inbound Parse has NO signature scheme. See the class-level SECURITY CAVEAT — consumers must protect the endpoint out-of-band.

      LIMITATION: binary attachment parts are intentionally NOT decoded. When attachment parts are present, only their COUNT is recorded (RawData.attachmentCount); the bytes are skipped. Consumers needing attachments must read the raw request directly.

      Parameters

      Returns Promise<ParseNotificationResult>

      Promise - One normalized notification, inline Message populated

    Settings

    Member Visibility

    On This Page

    SECURITY CAVEAT (Inbound Parse)
    Constructors
    Accessors
    Methods