SendGrid API compatible: change the URL and the key
SMTP Senpai accepts send requests in the same format as the SendGrid v3 Mail Send API. Point your code to SMTP Senpai, use your msp_ key and keep your SDK, your fields and your error handling.
14 days free · up to 100 emails a day · card required · if you don’t cancel within 14 days, the plan you chose starts
- Same paths, fields and errors
- Sending servers and log in the EU
- 14-day free trial
+ const client = require('@sendgrid/client'); const sgMail = require('@sendgrid/mail'); - sgMail.setApiKey(process.env.SENDGRID_API_KEY); + client.setApiKey(process.env.SMTP_SENPAI_KEY); // msp_… + client.setDefaultRequest('baseUrl', 'https://app.mailsenpai.com/relay/compat/sendgrid'); + sgMail.setClient(client);
Two things change, the rest stays
Same paths, same fields, same responses and error shapes as the SendGrid v3 Mail Send API.
The sender must be on a domain verified in your SMTP Senpai area and signed with DKIM: otherwise the request is refused with an error in the SendGrid format. To try without sending, use mail_settings.sandbox_mode: the request is checked and nothing leaves.
Your code, pointed to SMTP Senpai
const client = require('@sendgrid/client');
const sgMail = require('@sendgrid/mail');
client.setApiKey(process.env.SMTP_SENPAI_KEY); // msp_…
client.setDefaultRequest('baseUrl', 'https://app.mailsenpai.com/relay/compat/sendgrid');
sgMail.setClient(client);Tested with @sendgrid/mail 8.1.6: run with the official SDK against the SMTP Senpai endpoints.
import os
from sendgrid import SendGridAPIClient
sg = SendGridAPIClient(os.environ['SMTP_SENPAI_KEY'], # msp_…
host='https://app.mailsenpai.com/relay/compat/sendgrid')Tested with sendgrid 6.12.5 against SMTP Senpai: connection, authentication and error handling.
Other languages and frameworks
Settings read in the source code of each SDK: they follow the same rule (base URL or host, plus your key). Try them with a test send before going live.
| SDK | Setting | Status |
|---|---|---|
| PHP sendgrid/sendgrid | new \SendGrid($key, ['host' => 'https://app.mailsenpai.com/relay/compat/sendgrid']) | Read in the SDK source code, not yet tested |
| Ruby sendgrid-ruby | SendGrid::API.new(api_key: key, host: 'https://app.mailsenpai.com/relay/compat/sendgrid') | Read in the SDK source code, not yet tested |
| C# SendGrid | new SendGridClient(new SendGridClientOptions { ApiKey = key, Host = "https://app.mailsenpai.com/relay/compat/sendgrid" }) | Read in the SDK source code, not yet tested |
| Java sendgrid-java | sg.setHost("sendgrid-api.mailsenpai.com") | Read in the SDK source code, not yet tested |
| Symfony Mailer | MAILER_DSN=sendgrid+api://[email protected] | Read in the SDK source code, not yet tested |
What works, what is ignored, what is refused
Works
personalizations (to, cc, bcc, subject, headers, substitutions, from), from, reply_to, content text/plain + text/html, attachments (inline + content_id), headers, mail_settings.sandbox_mode, gzip
Accepted without effect
categories, custom_args, ip_pool_name, batch_id, tracking_settings, mail_settings.bypass_*
Named in the X-MailSenpai-Ignored response header.
Refused with the SendGrid error
template_id, dynamic_template_data, sections, send_at, asm, mail_settings.footer (400)
The warning «API key does not start with SG.» printed by the Node SDK is harmless. Do not call setDataResidency(): it overwrites the base URL. Unsubscribe groups (asm) are refused: use the List-Unsubscribe headers instead.
Delivery results from the SMTP Senpai API
The SendGrid endpoints for logs, events, statistics and webhooks are not reproduced. Results (sent, delivered, bounce, defer, complaint, dropped, open, click) come from the SMTP Senpai API with the same key: GET /relay/v1/eventi, or a signed webhook set in your SMTP Senpai area.
The id in the send response (X-Message-Id) is the message_id of those events. Each response also carries X-MailSenpai-Result (sent, queued, suppressed, failed).
Read the events and webhook reference
curl "https://app.mailsenpai.com/relay/v1/eventi?quanti=50" \
-H "Authorization: Bearer $SMTP_SENPAI_KEY"
# {"ok": true, "eventi": [{"type": "delivered",
# "email": "…", "message_id": "…", …}], "prossimo": …}Frequently asked questions
Do I have to rewrite my SendGrid code?
No. You change the base URL (or the host) and the key. Paths, fields, responses and the error format stay those of the SendGrid v3 Mail Send API, so your SDK and your error handling keep working.
What about templates and scheduled sending?
They are not supported: requests that use them are refused with the native error, so nothing leaves by mistake. Build the final content in your code and send it when you want it to leave.
How do I get bounces, opens and webhooks?
From the SMTP Senpai API, with the same key: GET /relay/v1/eventi or a signed webhook set in your SMTP Senpai area. The SendGrid event and webhook endpoints are not reproduced.
Can I test without sending?
Yes, as with SendGrid: set mail_settings.sandbox_mode. The request is checked and nothing is sent.
Can I keep sending through SMTP?
Yes. The same account also works over SMTP (relay.mailsenpai.com, port 2525, STARTTLS) and with the SMTP Senpai REST API.
The other formats SMTP Senpai accepts
All 14 compatible APIs
The table with every base URL, dedicated host and key.
OpenMailgun API compatible
Mailgun Messages API
OpenAmazon SES API compatible
Amazon SES API (v2 SendEmail, v1 SendEmail and SendRawEmail)
OpenPostmark API compatible
Postmark Email API
OpenResend API compatible
Resend Emails API
OpenBrevo API compatible
Brevo transactional email API
OpenTry SMTP Senpai with your current code
14 days to change the base URL and the key, send your real emails and check every result in the log. Then decide.
SendGrid is a trademark of Twilio Inc. or its affiliates. It is named only to describe the request format SMTP Senpai accepts. MailSenpai is not affiliated with Twilio and this page is not approved by them. Information checked on 9 October 2026.