Guide
Choose between the API and SMTP
Compare the Emailit REST API with the SMTP relay feature by feature, from templates and scheduling to idempotency and webhooks, and pick the right one.
Emailit accepts transactional email two ways: the REST API and the SMTP relay. This guide compares them so you can pick one, or use both in the same workspace.
The short answer
- Use the API for new code. It does more: templates, scheduling, idempotent retries, metadata, per-email tracking settings and a JSON response with an ID for every recipient.
- Use SMTP when the software you run already has SMTP settings, such as a CMS, a framework mailer, a helpdesk, a device or a legacy app. You change four settings and you’re done.
Both use the same API keys, verified domains, suppression list, sending limits, logs and webhooks. You can switch later without touching DNS.
Feature comparison
| Feature | REST API | SMTP relay |
|---|---|---|
| Endpoint | POST https://api.emailit.com/v2/emails |
smtp.emailit.com, ports 587, 465, 2525, 2587 and 25 |
| Authentication | Authorization: Bearer secret_… |
AUTH PLAIN or LOGIN, username emailit, password = API key |
| Content | html, text, or a stored template |
A complete MIME message, sent as is |
| Templates and variables | template (ID or alias) plus variables, rendered with Temple |
Not available. Render the message before you send it. |
| Scheduling | scheduled_at with ISO 8601, a Unix timestamp or plain English such as tomorrow at 9am |
Not available. Email is queued right away. |
| Attachments | Base64 content or a url that Emailit downloads (up to 25 MB each). content_id makes an image inline. |
Standard MIME parts |
| Message size | 40 MB | 40 MB |
| Recipients per message | Up to 50 each in to, cc and bcc |
No fixed limit per transaction |
| Idempotency | Idempotency-Key header, replayed for 24 hours |
Not available. A retried transaction can send twice. |
| Metadata | meta object, returned in webhook payloads |
Not available |
| Custom headers | headers object |
Any header in the message |
| Open and click tracking | Per email with tracking, or the domain default |
The domain default only |
email.accepted and email.scheduled webhooks |
Yes | No. Later events such as email.delivered and email.bounced work the same. |
| Email IDs | Response has id, and ids with one ID per recipient |
Final reply 250 2.0.0 OK: queued as em_… |
| Errors | HTTP status codes with a JSON body | SMTP reply codes, for example 535 or 550 |
| Sending limits | Shared per workspace. 429 with ratelimit-* and retry-after headers. |
Shared per workspace. 452 replies. |
| Credits | 1 per recipient | 1 per recipient |
| Request log | Email APILogs, source API | Email APILogs, source SMTP |
After an email is accepted, both channels behave the same. Every recipient gets an em_ ID, appears in Email APIEmails, and can be canceled, retried or forwarded from the dashboard or the API.
When to use the API
Choose the API when you write the sending code yourself, especially if you need any of these:
- Templates. Designers edit a template in the dashboard and your code sends it by alias with
variables. See Templates. - Safe retries. Send an
Idempotency-Keywith each request and retry on network errors without sending twice. See Idempotency. - Scheduling. Send a reminder for tomorrow morning without your own job queue, and reschedule or cancel it until 3 minutes before it goes out. See Scheduling.
- Correlation. Attach your own IDs in
metaand match webhook events to your records. See Headers and metadata. - Clear errors. A
422for an unverified domain or a402for missing credits is easier to handle than an SMTP reply string.
When to use SMTP
Choose SMTP when you can’t or don’t want to change code:
- Off-the-shelf software such as WordPress, a helpdesk or a monitoring tool with an SMTP settings page.
- Framework mailers that already work over SMTP, such as Laravel, Rails, Django or Nodemailer. You can move to the API later.
- Quick migrations from another provider. Swap the host, port, username and password, then test.
- Devices and scripts that only speak SMTP, such as printers, scanners or cron jobs.
Things to know before you rely on SMTP:
- Emailit doesn’t read provider-specific headers over SMTP. Tracking follows the sending domain’s Track loads and Track clicks settings.
- Emailit replaces your
Message-IDheader with its own, and removes theReply-Toheader when it’s the same asFrom. - Always use TLS. Port 587 with STARTTLS is recommended, and 465 uses TLS from the first byte. See SMTP settings.
Use both
Many teams use both: the API for application email and SMTP for a CMS or internal tools. Use a separate API key for each so you can tell them apart in the logs, and regenerate one without breaking the other. A Sending Only key restricted to one domain is a good fit for SMTP credentials stored in third-party software. See API keys.