SendGrid and Twilio Integrations

Purpose and Scope

This page groups the two communications integrations that the self-hosting docs present as required for Workflows: SendGrid for outbound email delivery and Twilio for messaging and verification. Both integrations are configured through environment variables rather than through an OAuth callback route. That makes the setup straightforward, but also sensitive to copied secrets, verified sender state, and service identifiers. Use this page when preparing a Cal.diy environment that must send workflow email, SMS messages, or phone verification traffic through external providers.

Sources: apps/docs/content/apps/sendgrid.mdx, apps/docs/content/apps/twilio.mdx

The important distinction is that SendGrid identifies the email sender and API authorization, while Twilio identifies several separate messaging capabilities. Twilio requires the account credentials, a phone number, an optional public sender display name, a Messaging Service SID, and a Verify Service SID. Those values are not interchangeable. If a deployment has a valid Twilio account SID and token but lacks the messaging or verify service identifiers, only part of the communications setup is complete, and workflow paths that depend on those services can still fail.

Sources: apps/docs/content/apps/sendgrid.mdx, apps/docs/content/apps/twilio.mdx

Relevant Source Files

• apps/docs/content/apps/sendgrid.mdx — First-party setup guide for creating a SendGrid account, generating the API key, verifying a sender, and placing the SendGrid variables in the environment.
• apps/docs/content/apps/twilio.mdx — First-party setup guide for creating a Twilio account, phone number, Messaging Service, Verify Service, and the Twilio environment variables used by Cal.diy.

Configuration Reference

A minimal communications environment therefore has two SendGrid variables and six Twilio variables. The SendGrid values come from two different provider tasks: creating an API key and verifying a single sender email. The Twilio values come from a longer provider setup because the account itself, phone number, messaging service, and verify service are separate resources in the Twilio dashboard. Keep these values together in deployment documentation, but collect them in the provider order shown by the docs so that each later step can reuse the resource created earlier.

Sources: apps/docs/content/apps/sendgrid.mdx, apps/docs/content/apps/twilio.mdx

# SendGrid
SENDGRID_API_KEY=replace-with-sendgrid-api-key
SENDGRID_EMAIL=verified-sender@example.com
 
# Twilio
TWILIO_SID=replace-with-account-sid
TWILIO_TOKEN=replace-with-auth-token
TWILIO_PHONE_NUMBER=+15551234567
NEXT_PUBLIC_SENDER_ID=Cal
TWILIO_MESSAGING_SID=replace-with-messaging-service-sid
TWILIO_VERIFY_SID=replace-with-verify-service-sid

SendGrid Setup Flow

Start the email side by creating a SendGrid account, then generate an API key from the SendGrid settings area. The Cal.diy documentation names that key as the value for SENDGRID_API_KEY. After the key exists, complete sender authentication by verifying a single sender email address. The verified address becomes SENDGRID_EMAIL. The ordering matters because the provider must trust the sender identity before the application can reliably send mail from that address, and a copied email address that has not completed verification is not equivalent to a verified sender.

Sources: apps/docs/content/apps/sendgrid.mdx

For operators, the practical validation step is to confirm both that the key has been copied without truncation and that the sender address is exactly the verified address shown by SendGrid. The docs do not describe multiple senders or domain-wide authentication on this page; they describe a single verified sender. That keeps the integration small and predictable for a self-hosted deployment. If mail does not appear after configuration, check the provider account status and sender authentication before changing unrelated Cal.diy application settings.

Sources: apps/docs/content/apps/sendgrid.mdx

Twilio Setup Flow

Twilio setup has more moving parts because account authorization, sender identity, messaging delivery, and verification are modeled as separate resources. Create the account first, obtain a Twilio phone number, then copy the Account SID, Auth Token, and phone number into the corresponding environment variables. The documentation also allows a custom sender ID through NEXT_PUBLIC_SENDER_ID and states that the fallback is Cal when this value is not specified. Treat that value as presentation configuration, not as a replacement for the Twilio phone number or service SIDs.

Sources: apps/docs/content/apps/twilio.mdx

After the base account values are present, create a Messaging Service from the Twilio dashboard under the messaging services area. Name the service, add senders, choose phone number as the sender type, and attach the Twilio phone number created earlier. Once the service is complete, copy the Messaging Service SID into TWILIO_MESSAGING_SID. This SID links the application configuration to the Twilio resource that owns the sender pool, so it should be updated if the deployment changes to a different messaging service.

Sources: apps/docs/content/apps/twilio.mdx

The final Twilio resource is the Verify Service. Create a Verify Service in the Twilio dashboard, name it, and copy its SID into TWILIO_VERIFY_SID. Do not reuse the Messaging Service SID for verification; the docs call out a separate Verify Service and a separate environment variable. This separation is useful during troubleshooting because message delivery failures and verification failures can be investigated independently. It also means rotating or recreating one Twilio service does not automatically update the other configured capability.

Sources: apps/docs/content/apps/twilio.mdx

Operational Notes and Next Steps

Because both pages describe secrets stored in the environment, treat the resulting values as deployment configuration rather than source-controlled application code. Keep the generated API keys, auth tokens, and service SIDs out of commits, screenshots, and issue reports. When promoting from a local environment to a hosted instance, copy the same variable names into the target platform’s secret manager or environment configuration. Then restart or redeploy the application so the runtime process reads the new values.

Sources: apps/docs/content/apps/sendgrid.mdx, apps/docs/content/apps/twilio.mdx

When communications still do not work, narrow the problem by provider and resource. For SendGrid, verify the API key and sender authentication. For Twilio, verify the account SID and token first, then confirm the phone number is attached to the Messaging Service, and finally confirm the Verify Service SID is separate and current. After this page, read the broader app integration pages if you are configuring additional providers, or the troubleshooting pages if the deployment starts but runtime communication features fail.