SendGrid

​

At a glance

npx @deploybaseline/cli start --service sendgrid

import { createEmulator } from "@deploybaseline/cli";

const sendgrid = await createEmulator({ service: "sendgrid" });
// sendgrid.url is http://localhost:4000

{
  "sendgrid": {
    "api_keys": [
      {
        "name": "Local key",
        "key": "SG.baseline_local.local_secret_for_development_only"
      }
    ],
    "templates": [
      {
        "name": "Welcome",
        "generation": "dynamic",
        "versions": [
          {
            "subject": "Welcome, {{name}}",
            "html_content": "<p>Hello {{name}}, thanks for joining.</p>"
          }
        ]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service sendgrid

import { Client } from "@sendgrid/client";
import { MailService } from "@sendgrid/mail";

const client = new Client();
client.setApiKey("SG.baseline_local.local_secret_for_development_only");
client.setDefaultRequest("baseUrl", `${process.env.SENDGRID_EMULATOR_URL}/`);

const mail = new MailService();
mail.setClient(client);

await mail.send({
  to: "[email protected]",
  from: "[email protected]",
  templateId: "d-0123456789abcdef0123456789abcdef",
  dynamicTemplateData: { name: "Ada" },
});

​

URL mapping

​

Auth

​

Errors

​

Mail Send

• personalizations (1 to 1000), each with to, cc, bcc, subject, headers, substitutions, dynamic_template_data, custom_args, and send_at
• from, reply_to or reply_to_list, subject, and content (text/plain first, then text/html)
• attachments in base64; disposition: inline needs a content_id
• template_id, categories (up to 10), custom_args, headers (reserved headers are refused), send_at, batch_id, asm, and ip_pool_name
• mail_settings.sandbox_mode and mail_settings.footer

• {{name}} (HTML escaped) and {{{html}}}
• {{#if}}, {{else}}, {{else if}}, {{#unless}}, and {{#with}}
• {{#each}} with this, @index, @key, @first, @last, ../, and @root
• {{#equals a b}}, {{#notEquals}}, {{#greaterThan}}, {{#lessThan}}, {{#and}}, and {{#or}}
• {{insert x "default=y"}}, {{formatDate d "YYYY-MM-DD"}}, and {{length list}}
• comments and ~ whitespace control

​

Scheduling

​

Templates

​

API keys

​

Marketing

​

Contacts

• PUT /v3/marketing/contacts — Upsert contacts: takes { list_ids?, contacts: [{ email, first_name, ..., custom_fields }] }, upserts by email, and returns { job_id }; read the job at GET /v3/marketing/contacts/imports/{job_id}
• GET /v3/marketing/contacts — List contacts
• GET /v3/marketing/contacts/{id} — Get contact
• DELETE /v3/marketing/contacts?ids= or ?delete_all_contacts=true — Delete contacts
• GET /v3/marketing/contacts/count — Count contacts
• POST /v3/marketing/contacts/batch — Get contacts by id: with { ids }
• POST /v3/marketing/contacts/search/emails — Search contacts by email: with { emails }
• POST /v3/marketing/contacts/search — Search contacts: with an SGQL query, such as email LIKE 'ada%' AND CONTAINS(list_ids, '<list id>')

​

Lists

• /v3/marketing/lists: create, list, get (contact_sample=true), rename, and delete (delete_contacts=true)
• DELETE /v3/marketing/lists/{id}/contacts?contact_ids= — Remove contacts from a list
• GET /v3/marketing/lists/{id}/contacts/count — Count list contacts

​

Suppressions

• GET and DELETE /v3/suppression/bounces ({ delete_all: true } or { emails }), and GET and DELETE /v3/suppression/bounces/{email}
• GET /v3/suppression/spam_reports and DELETE /v3/suppression/spam_reports/{email} — Spam reports: list them, or delete one by email
• GET /v3/suppression/unsubscribes — List unsubscribes

​

Event Webhook

import { EventWebhook, EventWebhookHeader } from "@sendgrid/eventwebhook";

const ew = new EventWebhook();
const ok = ew.verifySignature(
  ew.convertPublicKeyToECDSA(publicKey),
  rawBody,
  req.headers[EventWebhookHeader.SIGNATURE().toLowerCase()],
  req.headers[EventWebhookHeader.TIMESTAMP().toLowerCase()],
);

​

Simulate

curl -X POST "$SENDGRID_EMULATOR_URL/_sendgrid/simulate/bounce" \
  -H "Content-Type: application/json" -d '{"email":"[email protected]"}'

​

Seed config

{
  "sendgrid": {
    "api_keys": [
      {
        "name": "Local key",
        "key": "SG.baseline_local.local_secret_for_development_only"
      },
      {
        "name": "Send only",
        "scopes": ["mail.send"]
      }
    ],
    "templates": [
      {
        "name": "Welcome",
        "id": "d-0123456789abcdef0123456789abcdef",
        "versions": [
          {
            "subject": "Welcome, {{name}}",
            "html_content": "<p>Hello {{name}}</p>",
            "plain_content": "Hello {{name}}"
          }
        ]
      }
    ],
    "lists": [
      {
        "name": "Newsletter"
      }
    ],
    "contacts": [
      {
        "email": "[email protected]",
        "first_name": "Ada",
        "lists": ["Newsletter"]
      }
    ],
    "webhooks": [
      {
        "url": "http://localhost:3000/sendgrid/events",
        "events": ["processed", "delivered", "bounce"],
        "signed": true
      }
    ],
    "suppressions": {
      "bounces": ["[email protected]"]
    }
  }
}

• id: generated when left out

​

Inbox and inspector

​

Limits

• No SMTP relay, Single Sends, Automations, segments, custom field definitions, subusers, IP pools, or stats.
• Open and click tracking rewrite nothing; use the simulate routes for engagement events.
• Webhook retries run three times over about 20 seconds, where SendGrid retries for 24 hours.

​

Conformance