Migrate from SendGrid.

The send call, before and after

Before, with SendGrid's v3 mail send API (see SendGrid's docs for your library version):

1import sgMail from "@sendgrid/mail";
2​
3sgMail.setApiKey(process.env.SENDGRID_API_KEY);
4await sgMail.send({ from: "ada@yourdomain.com", to: "you@example.com", subject: "Hello", html: "<p>It works.</p>" });

1curl -X POST https://api.sendgrid.com/v3/mail/send \
2  -H "Authorization: Bearer $SENDGRID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{ "personalizations": [{ "to": [{ "email": "you@example.com" }] }], "from": { "email": "ada@yourdomain.com" }, "subject": "Hello", "content": [{ "type": "text/html", "value": "<p>It works.</p>" }] }'

After, with Mailtruss:

1import { MailClient } from "mailtruss";
2​
3const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
4const { id } = await mail.emails.send({ from: "ada@yourdomain.com", to: "you@example.com", subject: "Hello", html: "<p>It works.</p>" });

1curl -X POST https://mailtruss.com/api/v1/emails \
2  -H "Authorization: Bearer $MAILTRUSS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{ "from": "ada@yourdomain.com", "to": "you@example.com", "subject": "Hello", "html": "<p>It works.</p>" }'

The main change is the body: SendGrid nests recipients in personalizations and the sender in an object, and takes the content as a list of typed parts. Mailtruss takes from, to, subject, html and text as plain fields. SendGrid answers a send with 202 and no body; Mailtruss returns the new email's id, which you can use to fetch its delivery trace. Other languages are under send email by language.

If you send over SMTP

Apps that use SendGrid's SMTP relay only need new settings. SendGrid's relay uses the literal username apikey with an API key as the password. Mailtruss takes any username with an API key as the password:

1host: smtp.sendgrid.net
2port: 587
3username: apikey
4password: <your SendGrid API key>

1host: smtp.mailtruss.com
2port: 587 (STARTTLS) or 465 (TLS)
3username: mailtruss   # any value works
4password: <your Mailtruss API key>

Details and framework examples are on the SMTP page and in the integration guides.

What maps to what

• Several recipients: to, cc and bcc take lists. To send different messages to different people, use POST /api/v1/emails/batch.
• Dynamic templates: a Mailtruss template is sent by ID with a variables object, and only the published version is ever sent. See Sending.
• Categories and custom arguments: roughly tags, which are name and value pairs you can filter by.
• Unsubscribe groups: topics, which people can switch on or off from the unsubscribe page without leaving everything.
• Scheduling: scheduled_at takes an ISO 8601 time.
• Attachments: base64 content with a filename.
• Marketing contacts and campaigns: contacts, segments and broadcasts.

Webhooks

SendGrid signs its event webhook with its own scheme, so verification code has to change. Mailtruss signs webhooks with the Standard Webhooks scheme, and the client libraries include a verifyWebhook helper. Events have different names (email.delivered, email.bounced, email.complained), so map them in your handler. See Webhooks.

A safe order to switch

1. Create an account and verify your sending domain (DNS records). Verification here is separate from SendGrid's, and the records differ.
2. Create a key and send a test to delivered@mailtruss.test, so nothing reaches a real inbox.
3. Change the client, the key and the request body in one place in your code.
4. Point your webhook handler at the new signing secret and event names, then send real mail.
5. Keep SendGrid active for a few days while you watch the first real sends, then switch it off.

Comparing costs first? See Mailtruss vs SendGrid, which uses SendGrid's own published prices. Mailtruss's are on the pricing page.