Lumbox handles the agent side of email: inboxes, receiving, parsing, threads, webhooks. Something still has to hand outbound messages to the internet, and by default that is a delivery service Lumbox runs. Bring your own SMTP (BYOS) means registering your own provider account instead, so mail from your domain goes out through your account: your sending limits, your provider's logs, your dedicated IPs if you pay for them, and your contract. This post covers which sends it actually affects, how to configure each provider, and what happens when the provider fails.
Which sends use your provider
This is the part most people get wrong, so start here. Lumbox picks the delivery path from the domain of the From address, not from which configurations exist:
| Sending from | Delivered by |
|---|---|
An inbox on trylumbox.com | Lumbox's Amazon SES account, always. Your configuration is not used. |
| An inbox on your verified domain | Your organization's default configuration. Without one, Lumbox's default provider. |
POST /v1/send/bulk and contact-list sends | Resend, always. A default configuration of type RESEND supplies the API key; any other type is ignored for these. |
So BYOS only matters once you have a custom domain with inboxes on it, and only for single sends, replies and forwards, unless your provider is Resend. The custom domain guide covers getting a domain to ACTIVE.
Supported providers and their fields
Configurations live at /v1/smtp-configs. The API accepts seven provider types:
provider | Required fields | Notes |
|---|---|---|
SMTP | host | port defaults to 587; port 465 uses implicit TLS. username and password if the server needs auth. |
SES | username, password | The access key ID goes in username and the secret in password. region defaults to us-east-1. Sends through the SES v2 API, not SMTP. |
SENDGRID | api_key | |
POSTMARK | api_key | The server token. |
RESEND | api_key | Also used for bulk and contact-list sends. |
MAILCHIMP | api_key | A Mailchimp Transactional (Mandrill) key. |
KLAVIYO | api_key | A private API key. |
Some older write-ups, including an earlier version of this post, used field names like aws_access_key_id and from_domain. Those do not exist. The body is { provider, name?, host?, port?, username?, password?, api_key?, region?, from_name?, from_email?, is_default? }, and a missing required field returns a 400 that names it.
Setting up Amazon SES
curl -X POST https://api.lumbox.co/v1/smtp-configs \
-H "X-API-Key: ak_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "ses-prod",
"provider": "SES",
"username": "AKIA...",
"password": "your_secret_access_key",
"region": "eu-west-1",
"from_email": "ops@agents.example.com",
"is_default": true
}'Before this works, three things have to be true in your AWS account, and none of them are checked when you save the configuration:
- The domain is a verified SES identity in that same region. SES identities are regional, so a domain verified in
us-east-1cannot send througheu-west-1. - The account is out of the SES sandbox. A sandboxed account can only send to verified addresses and the mailbox simulator, at most 200 messages in 24 hours and one per second. Everything else is rejected, which looks like a broken integration when it is a pending AWS request.
- The key belongs to an IAM user that can send and do nothing else. The secret is stored encrypted, but it is still a credential that leaves your account.
The same idea applies to every provider: the provider account has to accept mail from your domain, which usually means verifying the domain there and publishing that provider's DKIM records.
Test it, then make it the default
curl -X POST https://api.lumbox.co/v1/smtp-configs/smc_.../test \
-H "X-API-Key: ak_your_key" \
-H "Content-Type: application/json" \
-d '{"to": "you@example.com"}'
# 200 { "ok": true, "message_id": "...", "provider": "ses" }
# 400 { "ok": false, "error": "SES error 403: ..." }The test sends a short message with the subject "Lumbox SMTP Test" straight through that configuration. It is sent from the configuration's from_email, and if you left that empty, from the test recipient's own address, which most providers will refuse. Set from_email to an address on your verified domain. A 400 carries the provider's own error text, which is usually specific enough to act on.
An organization has one default configuration. Creating one with "is_default": true clears the flag on the others, and PATCH /v1/smtp-configs/{id}/default switches it later. That means one provider per organization, not per domain or per inbox. If two of your domains need two different providers, that is not something the current routing supports.
Listing configurations with GET /v1/smtp-configs never returns secrets. Passwords and API keys are encrypted with AES-256-GCM at rest, and the list shows only the first four characters of the username plus has_password and has_api_key flags.
DNS when someone else delivers
With your own provider sending, authentication comes from that provider: its DKIM keys and, where it uses one, its SPF include. Lumbox's sending records for the domain do not authenticate mail that Lumbox did not send. Receiving is unchanged, because inbound mail still arrives at Lumbox through your MX records.
One quirk: Lumbox's verify check will not mark a domain ACTIVE unless its SPF record contains include:spf.lumbox.co, and inboxes can only be created on an ACTIVE domain. Keep that include in the record alongside your provider's include, as a single merged SPF record. The SPF, DKIM and DMARC post explains why the DKIM records are the ones that decide DMARC.
When the provider fails
There is no fallback. If your provider rejects a message, times out or is down, the send returns 500 with Failed to send: followed by the provider's error, and Lumbox does not retry through its own service. An earlier version of this post said otherwise; that was wrong. For many teams this is the behaviour they want anyway, since the point of BYOS is that mail from the domain only ever leaves through their account.
Every provider failure comes back as that same 500, whether it is a timeout or a permanent refusal such as an unverified sender, so the status code alone does not tell the agent whether to retry. Read the error text: a network error or a 5xx from the provider is worth retrying with backoff, while a provider 4xx will fail the same way every time. Keep the same Idempotency-Key across retries. It covers the case where Lumbox sent the message and the response was lost on the way back to the agent. It cannot cover a provider that accepted the message and then timed out, because Lumbox reports that as a failure and releases the key. The response's provider field shows which service handled each message (ses, smtp, sendgrid, postmark, resend, mailchimp or klaviyo), which is the quickest way to confirm the routing is what you expect.
Provider-side features stay on the provider side. Bounce and complaint handling, dedicated IP pools, and delivery logs are in your provider's dashboard, not in Lumbox, and Lumbox's own bounce-based suppression is fed by Amazon SES notifications to Lumbox, which your separate account does not send. The outbound API guide covers the send, reply and forward calls that run on top of whichever provider you choose.