SendGrid

Learn how the Skrym-SendGrid integration works

SendGrid is a powerful email delivery service that allows you to send transactional and marketing emails with ease. Integrating SendGrid with Skrym enables you to leverage its capabilities for your email communication needs.

Info
This integration currently supports dynamic templates only. Legacy templates are not supported.

Prerequisites

Before setting up the integration, you'll need:

An active SendGrid account
A SendGrid API key with appropriate permissions
Dynamic templates created in your SendGrid account (optional, but recommended for testing)

Creating a SendGrid API Key

To connect Skrym with SendGrid, you'll need to create an API key in your SendGrid account:

Log in to your SendGrid account
Navigate to Settings > API Keys
Click Create API Key
Give your API key a descriptive name (e.g., "Skrym Integration")
Select the appropriate permission level:
- Restricted Access (recommended) with at least the following permissions:
  - Mail Send: Full Access
  - Template Engine: Read Access
- Full Access (not recommended) should only be used as a last resort if you explicitly need additional SendGrid capabilities beyond sending mail and reading templates, or when troubleshooting permission-related issues.
Click Create & View
Important: Copy the API key immediately - you won't be able to see it again!

For detailed instructions, refer to the official SendGrid documentation on API keys.

Setup

Once you have your SendGrid API key, follow these steps to configure the integration in Skrym:

Navigate to Integrations in the Skrym dashboard
Go to the Systems tab
Find the SendGrid integration card and click Configure or Connect
In the configuration dialog:
- Name: Enter a descriptive name for this integration (e.g., "Production SendGrid")
- API Key: Paste the API key you created in SendGrid
Click Save to store your credentials securely

Warning
Security Note: Your API key is encrypted before being stored in Skrym's database. Once saved, you can only update or delete the credentials - you cannot view the original API key again.

Testing the Connection

After saving your credentials, you can test the connection:

Click the Test Connection button in the configuration dialog
If successful, Skrym will fetch and display your dynamic templates from SendGrid
The templates table shows:
- Preview thumbnails (when available)
- Template names
- Template IDs
- Number of versions

Usage

Email triggers in Skrym allow you to automatically send transactional emails when specific milestones in an order journey are completed. These emails are sent through SendGrid using dynamic templates that have access to comprehensive order and shipment data.

How it works

When a milestone is completed in an order journey:

Skrym evaluates all active triggers associated with that milestone
For email triggers, the system:
- Fetches the complete order information including shipments, events, and locations
- Combines this data with trigger metadata
- Sends it to SendGrid using your configured dynamic template
- Delivers the email to the customer

Template Data Structure

Your SendGrid dynamic templates receive a JSON object with the following structure:

{
  "trigger": {
    // Metadata about the trigger event
  },
  "order": {
    // Complete order information
  }
}

Trigger Object

The trigger object contains metadata about the milestone completion event:

Order Object

The order object contains comprehensive information about the order:

Using Data in SendGrid Templates

SendGrid uses Handlebars syntax to access template data. Here are common use cases:

Basic Information:

{/* Access trigger information */}
{{trigger.milestoneReference}}
{{trigger.timestamp}}

{/* Access order references */}
{{order.Order.id}}
{{#each order.References}}
  {{this.reference}}
{{/each}}

Destination Address:

{{#if order.Destination}}
  {{order.Destination.address}}
  {{order.Destination.city}}, {{order.Destination.postalCode}}
  {{order.Destination.countryCode}}
{{/if}}

Shipment Tracking:

{{#if trigger.trackingLink}}
  <a href="{{trigger.trackingLink}}">Track your shipment</a>
{{/if}}

{/* Or access from shipment data */}
{{#each order.Shipments}}
  {{#if this.Shipment.trackingReference}}
    Tracking: {{this.Shipment.trackingReference}}
  {{/if}}
{{/each}}

Sample HTML Template

Here's a complete example of a transactional email template for an "Order Shipped" notification:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Order Has Shipped</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
      line-height: 1.6;
      color: #1f2937;
      max-width: 600px;
      margin: 0 auto;
      padding: 20px;
      background-color: #f9fafb;
    }
    .container {
      background: #ffffff;
      border-radius: 8px;
      overflow: hidden;
      box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
    }
    .header {
      background: #2563eb;
      color: white;
      padding: 32px 24px;
      text-align: center;
    }
    .header h1 {
      margin: 0;
      font-size: 24px;
      font-weight: 600;
    }
    .content {
      padding: 32px 24px;
    }
    .section {
      background: #f9fafb;
      padding: 20px;
      border-radius: 6px;
      margin: 20px 0;
      border: 1px solid #e5e7eb;
    }
    .section h3 {
      margin-top: 0;
      margin-bottom: 16px;
      font-size: 18px;
      font-weight: 600;
      color: #1f2937;
    }
    .info-row {
      display: flex;
      justify-content: space-between;
      padding: 10px 0;
      border-bottom: 1px solid #e5e7eb;
    }
    .info-row:last-child {
      border-bottom: none;
    }
    .label {
      font-weight: 500;
      color: #6b7280;
    }
    .value {
      color: #1f2937;
      font-weight: 400;
    }
    .tracking-button {
      display: inline-block;
      background: #2563eb;
      color: white;
      padding: 12px 28px;
      text-decoration: none;
      border-radius: 6px;
      margin: 24px 0;
      font-weight: 500;
      text-align: center;
    }
    .tracking-button:hover {
      background: #1d4ed8;
    }
    .button-container {
      text-align: center;
    }
    .footer {
      text-align: center;
      color: #6b7280;
      font-size: 14px;
      padding: 24px;
      border-top: 1px solid #e5e7eb;
    }
    .footer p {
      margin: 4px 0;
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="header">
      <h1>📦 Your Order Has Shipped!</h1>
    </div>
    
    <div class="content">
      <p>Great news! Your order is on its way to you.</p>
      
      <div class="section">
        <h3>Order Details</h3>
        
        <div class="info-row">
          <span class="label">Order ID:</span>
          <span class="value">{{order.Order.id}}</span>
        </div>
        
        {{#each order.References}}
        <div class="info-row">
          <span class="label">Reference:</span>
          <span class="value">{{this.reference}}</span>
        </div>
        {{/each}}
        
        <div class="info-row">
          <span class="label">Milestone:</span>
          <span class="value">{{trigger.milestoneReference}}</span>
        </div>
        
        <div class="info-row">
          <span class="label">Status Updated:</span>
          <span class="value">{{trigger.timestamp}}</span>
        </div>
      </div>
      
      {{#if order.Destination}}
      <div class="section">
        <h3>Delivery Address</h3>
        <p style="margin: 0;">
          {{#if order.Destination.name}}{{order.Destination.name}}<br>{{/if}}
          {{order.Destination.address}}<br>
          {{order.Destination.city}}, {{order.Destination.postalCode}}<br>
          {{order.Destination.countryCode}}
        </p>
      </div>
      {{/if}}
      
      {{#each order.Shipments}}
      <div class="section">
        <h3>Shipment Information</h3>
        
        {{#if this.Shipment.trackingReference}}
        <div class="info-row">
          <span class="label">Tracking Number:</span>
          <span class="value">{{this.Shipment.trackingReference}}</span>
        </div>
        {{/if}}
        
        {{#if this.PromisedDeliveryTimeStart}}
        <div class="info-row">
          <span class="label">Estimated Delivery:</span>
          <span class="value">{{this.PromisedDeliveryTimeStart}}</span>
        </div>
        {{/if}}
        
        {{#if this.Events}}
        <h4 style="margin-top: 16px; margin-bottom: 8px; font-size: 16px;">Recent Updates:</h4>
        {{#each this.Events}}
          {{#if @first}}
          <p style="margin: 0;"><strong>{{this.eventType}}</strong> - {{this.timestamp}}</p>
          {{/if}}
        {{/each}}
        {{/if}}
      </div>
      {{/each}}
      
      {{#if trigger.trackingLink}}
      <div class="button-container">
        <a href="{{trigger.trackingLink}}" class="tracking-button">
          Track Your Shipment
        </a>
      </div>
      {{/if}}
      
      <p>If you have any questions about your order, please don't hesitate to contact our support team.</p>
    </div>
    
    <div class="footer">
      <p>This email was sent because a milestone in your order journey was completed.</p>
      <p>Journey: {{trigger.journeyReference}} | Milestone: {{trigger.milestoneReference}}</p>
    </div>
  </div>
</body>
</html>

Testing Email Triggers

You can test your email templates before activating them:

Navigate to your Order Journey in Skrym
Find the milestone with your email trigger
Click the Send test email button (paper plane icon)
Enter a test email address
Click Send

The test email will be sent with mock order data to verify your template rendering.

Warning
Note: The test button is only enabled for saved triggers. Make sure to save your journey before testing.

Best Practices

Handle Missing Data Gracefully - Always use conditional checks in your templates:

{{#if order.Destination}}
  {{order.Destination.address}}
{{else}}
  Address not available
{{/if}}

Keep Templates Responsive - Use responsive email design practices:

Mobile-first approach
Flexible widths
Clear call-to-action buttons
Readable font sizes

Test Thoroughly:

Test with various order scenarios (with/without tracking, different destinations, etc.)
Preview in multiple email clients
Use SendGrid's preview and test tools

Support

If you encounter any issues with the SendGrid integration, please contact Skrym support or refer to the SendGrid documentation for more information about SendGrid-specific features.

SendGrid

Trigger Object

Order Object

Search docs