QuickStartTutorialsDocumentationIntegrationsAPI ReferencePricingGet Started!
Documentation
LoginRegister

Drop-in SendGrid SDK

Already using the official SendGrid SDK? You can keep it and point it at Routee's SendGrid-compatible facade. Routee accepts the SendGrid Mail Send v3 payload shape, so migrating is mostly a matter of changing three things.

📘

What changes

SettingSendGridRoutee facade
Host / base URLhttps://api.sendgrid.comhttps://connect.routee.net
Path/v3/mail/send/transactional-email/sg/
API keySendGrid API keyYour Routee access token (a Bearer token)

The facade accepts the standard SendGrid fields — personalizations[].to[], cc, subject, content[], mail_settings.footer, and up to 10 custom headers. It also accepts Routee-native fields such as cc, bcc, attachments, footer, scheduledDate, label, and ttl.

📘

Get a Routee access token

The API key you pass to the SDK must be a Routee access token, not a SendGrid key. See Get authenticated to exchange your application credentials for one.

Node.js — @sendgrid/client

The high-level @sendgrid/mail send() helper posts to a fixed /v3/mail/send path, so use the official @sendgrid/client to control the path. Set the base URL, the Routee token, and post the SendGrid payload to the facade.

const client = require("@sendgrid/client");

// Use your Routee access token, not a SendGrid API key
client.setApiKey("YOUR_ROUTEE_ACCESS_TOKEN");
// Point the official SendGrid client at Routee
client.setDefaultRequest("baseUrl", "https://connect.routee.net");

const data = {
  personalizations: [
    { to: [{ email: "[email protected]", name: "Jane Customer" }] },
  ],
  from: { email: "[email protected]", name: "Acme Support" },
  subject: "Your order is confirmed",
  content: [{ type: "text/html", value: "<p>Thank you for your order, Jane.</p>" }],
};

const [response] = await client.request({
  method: "POST",
  url: "/transactional-email/sg/",
  body: data,
});

console.log(response.statusCode, response.body);

Python — SendGrid Mail helper

Build the payload with SendGrid's official Mail helper, then send it to the facade with the bundled python_http_client (installed with the sendgrid package). Creating the client without a version keeps the path exactly /transactional-email/sg/.

from sendgrid.helpers.mail import Mail, Email, To, Content
import python_http_client

message = Mail(
    from_email=Email("[email protected]", "Acme Support"),
    to_emails=To("[email protected]", "Jane Customer"),
    subject="Your order is confirmed",
    html_content=Content("text/html", "<p>Thank you for your order, Jane.</p>"),
)

client = python_http_client.Client(
    host="https://connect.routee.net",
    request_headers={
        "Authorization": "Bearer YOUR_ROUTEE_ACCESS_TOKEN",
        "Content-Type": "application/json",
    },
)

# Post the SendGrid payload to Routee's facade path
response = client._("transactional-email")._("sg").post(request_body=message.get())
print(response.status_code)
👍

Mix in Routee fields

Because the facade also understands Routee-native fields, you can add scheduledDate, label, ttl, bcc, or attachments to the same payload — handy when you want features that the SendGrid shape doesn't cover.

⚠️

Response shape

The facade follows Routee's behaviour: a 2xx means the message was accepted, and Routee returns a trackingId. Don't rely on SendGrid's X-Message-Id header.

Reference

Next steps