From e24ac9ac267f2119f94b5d64ead58a9bc7f36c24 Mon Sep 17 00:00:00 2001 From: Rutam21 Date: Fri, 20 Oct 2023 22:40:22 +0530 Subject: [PATCH 1/4] [TRI-1428] : Improve the SendGrid integration documentation --- docs/integrations/apis/sendgrid-tasks.mdx | 99 +++++++++++++++++++++++ docs/integrations/apis/sendgrid.mdx | 70 ++++++---------- docs/mint.json | 8 +- 3 files changed, 129 insertions(+), 48 deletions(-) create mode 100644 docs/integrations/apis/sendgrid-tasks.mdx diff --git a/docs/integrations/apis/sendgrid-tasks.mdx b/docs/integrations/apis/sendgrid-tasks.mdx new file mode 100644 index 0000000000..20e3297b78 --- /dev/null +++ b/docs/integrations/apis/sendgrid-tasks.mdx @@ -0,0 +1,99 @@ +--- +title: SendGrid tasks +sidebarTitle: Tasks +--- + +Tasks are executed after the job is triggered and are the main building blocks of a job. You can string together as many tasks as you want. + +--- + +## All tasks + +### `sendEmail` + +Send an email with a payload text. [Official SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email) + +```ts example.ts +run: async (payload, io, ctx) => { + // The 'run' function is asynchronous and takes 'payload,' 'io,' and 'ctx' as parameters. + + // Using the 'io.sendgrid.sendEmail' method to send an email using SendGrid. + await io.sendgrid.sendEmail({ + to: payload.to, // Recipient's email address, obtained from the 'payload' parameter. + from: "Trigger.dev ", // Sender's email address and name. + subject: payload.subject, // Email subject, obtained from the 'payload' parameter. + text: payload.text, // Plain text content of the email, obtained from the 'payload' parameter. + }); +} + +``` + +## Example usage + +In this example, we will send weekly summary emails to users who have `summariesEnabled = true`, at 4pm every Friday, and then posts the total numbers to Slack. + +```ts example.ts +import { TriggerClient, cronTrigger } from "@trigger.dev/sdk"; +import { SendGrid } from "@trigger.dev/sendgrid"; +import { Slack } from "@trigger.dev/slack"; +import { weeklySummaryDb } from "./mocks/db"; +import { weeklySummaryEmail } from "./mocks/emails"; + +// Creating an instance of the TriggerClient with a unique identifier "jobs-showcase." +const client = new TriggerClient({ id: "jobs-showcase" }); + +// Creating instances of SendGrid and Slack clients. +const sendgrid = new SendGrid({ + id: "sendgrid", + apiKey: process.env.SENDGRID_API_KEY!, +}); + +const slack = new Slack({ id: "slack" }); + +// Defining a job that sends a weekly summary email to users and posts total numbers to Slack. +client.defineJob({ + id: "weekly-user-activity-summary", // Unique identifier for the job. + name: "Weekly user activity summary", // A specific name for the job. + version: "1.0.0", // Version number for the job. + integrations: { sendgrid, slack }, // Integrating SendGrid and Slack clients into this job. + trigger: cronTrigger({ + // Setting a cron schedule to run the job every Friday at 4 pm. + cron: "0 16 * * 5", + }), + run: async (payload, io, ctx) => { + // Inside the 'run' function, several operations are performed to send weekly summaries and post to Slack. + + // Retrieving a list of users from the weeklySummaryDb. + const users = await weeklySummaryDb.getUsers(); + + let sentCount = 0; + let notSentCount = 0; + + // Iterating through the list of users. + for (const user of users) { + if (user.summariesEnabled) { + // Sending a weekly summary email to users with summaries enabled. + await io.sendgrid.sendEmail(`Weekly summary for ${user.id}`, { + to: user.email, + from: "hello@acme.inc", // The sender's email. + subject: "Your weekly summary", + html: weeklySummaryEmail(user), // HTML content for the email. + }); + sentCount++; + } else { + notSentCount++; + } + } + + // Posting a message to Slack with a summary of the sent and unsent emails. + await io.slack.postMessage("Notify team", { + text: `Weekly summary sent to ${sentCount} users and not sent to ${notSentCount} users`, + channel: "YOUR_CHANNEL_ID", // Specify the Slack channel ID for posting the message. + }); + }, +}); + +// If you're not using Express, you can remove these lines. +import { createExpressServer } from "@trigger.dev/express"; +createExpressServer(client); +``` diff --git a/docs/integrations/apis/sendgrid.mdx b/docs/integrations/apis/sendgrid.mdx index 82b5af5141..439ece5e45 100644 --- a/docs/integrations/apis/sendgrid.mdx +++ b/docs/integrations/apis/sendgrid.mdx @@ -1,10 +1,23 @@ --- -title: SendGrid +title: SendGrid overview & authentication +sidebarTitle: Overview & authentication --- - +## Overview -## Installation +SendGrid is a cloud-based SMTP provider that allows you to send email without having to maintain email servers. SendGrid +manages all of the technical details, from scaling the infrastructure to ISP outreach and reputation monitoring to whitelist +services and real time analytics. + + + Check out pre-built SendGrid jobs in our showcase. + + +## Installing the SendGrid packages @@ -35,50 +48,13 @@ const sendgrid = new SendGrid({ }); ``` -## Example - -In this example we use [Zod](/documentation/guides/zod), a TypeScript-first schema declaration and validation library. - -```ts -import { SendGrid } from "@trigger.dev/sendgrid"; -import { Job, eventTrigger } from "@trigger.dev/sdk"; -import { z } from "zod"; - -// Create an instance of SendGrid -const sendgrid = new SendGrid({ - id: "sendgrid", - apiKey: process.env.SENDGRID_API_KEY!, -}); - -// Define a Trigger.dev job -client.defineJob({ - id: "send-sendgrid-email", - name: "Send SendGrid Email", - version: "0.1.0", - trigger: eventTrigger({ - name: "send.email", - schema: z.object({ - to: z.string(), - subject: z.string(), - text: z.string(), - }), - }), - integrations: { - sendgrid, - }, - run: async (payload, io, ctx) => { - await io.sendgrid.sendEmail({ - to: payload.to, - from: "Trigger.dev ", - subject: payload.subject, - text: payload.text, - }); - }, -}); -``` ## Tasks -| Function Name | Description | -| ------------- | ------------- | -| `sendEmail` | Send an email | +Once you have set up a SendGrid client, you can use it to create tasks. + + + + Perform tasks such as sending emails to clients on certain trigger events. + + diff --git a/docs/mint.json b/docs/mint.json index 8c1399778d..bbe7b617f0 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -257,7 +257,13 @@ }, "integrations/apis/replicate", "integrations/apis/resend", - "integrations/apis/sendgrid", + { + "group": "SendGrid", + "pages": [ + "integrations/apis/sendgrid", + "integrations/apis/sendgrid-tasks" + ] + }, "integrations/apis/slack", "integrations/apis/stripe", { From 2306624169660be8178b0f0ca89297728f33d812 Mon Sep 17 00:00:00 2001 From: Rutam Prita Mishra Date: Mon, 23 Oct 2023 23:36:46 +0530 Subject: [PATCH 2/4] Added API Doc link in Overview. --- docs/integrations/apis/sendgrid.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/apis/sendgrid.mdx b/docs/integrations/apis/sendgrid.mdx index 439ece5e45..2f16543dca 100644 --- a/docs/integrations/apis/sendgrid.mdx +++ b/docs/integrations/apis/sendgrid.mdx @@ -37,7 +37,7 @@ yarn add @trigger.dev/sendgrid@latest ## Authentication -SendGrid integration supports API Keys. To authenticate, you'll need to create an instance of the SendGrid class and provide your API key. +SendGrid integration supports API Keys. To authenticate, you'll need to create an instance of the SendGrid class and provide your API key. You can find the official SendGrid documentation to configure an API key [here](https://docs.sendgrid.com/ui/account-and-settings/api-keys). ```ts import { SendGrid } from "@trigger.dev/sendgrid"; From dbc8dc90979a21f102cc70fcf70ee3e8ce5ee11f Mon Sep 17 00:00:00 2001 From: Rutam Prita Mishra Date: Tue, 24 Oct 2023 00:55:42 +0530 Subject: [PATCH 3/4] Fixed SendGrid Tasks to use generic values. --- docs/integrations/apis/sendgrid-tasks.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/integrations/apis/sendgrid-tasks.mdx b/docs/integrations/apis/sendgrid-tasks.mdx index 20e3297b78..6f57bec5b6 100644 --- a/docs/integrations/apis/sendgrid-tasks.mdx +++ b/docs/integrations/apis/sendgrid-tasks.mdx @@ -11,18 +11,18 @@ Tasks are executed after the job is triggered and are the main building blocks o ### `sendEmail` -Send an email with a payload text. [Official SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email) +Send an email with a body. [Official SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email) ```ts example.ts -run: async (payload, io, ctx) => { - // The 'run' function is asynchronous and takes 'payload,' 'io,' and 'ctx' as parameters. +run: async (io, ctx) => { + // The 'run' function is asynchronous and takes 'io' and 'ctx' as parameters. // Using the 'io.sendgrid.sendEmail' method to send an email using SendGrid. await io.sendgrid.sendEmail({ - to: payload.to, // Recipient's email address, obtained from the 'payload' parameter. - from: "Trigger.dev ", // Sender's email address and name. - subject: payload.subject, // Email subject, obtained from the 'payload' parameter. - text: payload.text, // Plain text content of the email, obtained from the 'payload' parameter. + to: , // Recipient's email address. + from: "Your-Name ", // Sender's email address and name. + subject: , // Email subject. + text: , // Plain text content of the email. }); } From 127ffd7272ef60d639ae6feca080647cb1e6b845 Mon Sep 17 00:00:00 2001 From: Rutam Prita Mishra Date: Thu, 26 Oct 2023 00:27:20 +0530 Subject: [PATCH 4/4] Update sendgrid-tasks.mdx --- docs/integrations/apis/sendgrid-tasks.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/integrations/apis/sendgrid-tasks.mdx b/docs/integrations/apis/sendgrid-tasks.mdx index 6f57bec5b6..cf0af9ffed 100644 --- a/docs/integrations/apis/sendgrid-tasks.mdx +++ b/docs/integrations/apis/sendgrid-tasks.mdx @@ -14,9 +14,6 @@ Tasks are executed after the job is triggered and are the main building blocks o Send an email with a body. [Official SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email) ```ts example.ts -run: async (io, ctx) => { - // The 'run' function is asynchronous and takes 'io' and 'ctx' as parameters. - // Using the 'io.sendgrid.sendEmail' method to send an email using SendGrid. await io.sendgrid.sendEmail({ to: , // Recipient's email address.