Skip to main content

Providers

Sending goes through apps/providers. Workers call EmailProvider.send and do not import a vendor SDK.

ProviderMessage -> EmailProvider.send(message, credentials) -> ProviderResult

ProviderResult.ok means the provider accepted the message. retryable schedules another attempt. error_code provider_unauthorized (HTTP 401 or 403) fails the message and pauses that company's lane until staff resume it.

Active names (ACTIVE_PROVIDER_NAMES): resend (default), ses, and smtp. mailjet is in the tree and is not registered, so the API rejects provider: "mailjet".

Resend​

Company credentials: {"api_key": "re_example"}.

The adapter POSTs https://api.resend.com/emails with Authorization: Bearer, User-Agent: shellui-email-service/1.0, and Idempotency-Key set to the message id. HTTP 429 and 5xx are retryable. 401 and 403 pause the lane.

Platform fallback (off by default): EMAIL_FALLBACK_PROVIDER=resend and RESEND_API_KEY, or EMAIL_FALLBACK_PROVIDER=ses with SES_ACCESS_KEY_ID, SES_SECRET_ACCESS_KEY and SES_REGION. See Integration for the fallback caps.

Inbound events: POST /api/v1/provider-webhooks/resend/{stream} with Svix verification. The {stream} segment is a label stored on the event. It does not pick a lane.

Resend account, before mail leaves​

Do this once for the platform Resend account, and again for every company that brings its own account.

An API key alone is not enough. Without the steps below, bounced and complained addresses keep receiving mail, delivery statuses stay at "handed to the provider", broadcasts fail, and an unsubscribe on Resend's page is never recorded here.

Verify two sending domains​

In Resend > Domains, add both and publish the DNS records Resend shows (DKIM, plus SPF and MX for the return path). Resend refuses to send from a domain that is not verified.

DomainSendsSetting
Main domain, for example shellui.comSign-in links, invitations, notificationsDEFAULT_FROM_EMAIL=no-reply@shellui.com
News subdomain, for example news.shellui.comBroadcasts and other bulk mailBULK_FROM_EMAIL=news@news.shellui.com

Complaints about news then stay off the domain that sends sign-in mail.

Create a Full access API key​

In Resend > API Keys, create a key with Full access and put it in RESEND_API_KEY.

A Sending access key sends single emails. It cannot create the segments, contacts, and broadcasts that Resend Broadcasts need. Every broadcast then fails with provider_unauthorized.

Add the webhook​

In Resend > Webhooks, add an endpoint:

  • URL: {PUBLIC_BASE_URL}/api/v1/provider-webhooks/resend/all, for example https://email.shellui.com/api/v1/provider-webhooks/resend/all
  • Events: email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.suppressed, and contact.updated. Leave email.opened and email.clicked off. email-service ignores them
  • Signing secret: copy the whsec_ value into RESEND_WEBHOOK_SECRET
EventsWhat breaks without them
email.sent, email.delivered, email.delivery_delayed, email.failed, email.suppressedStatuses stop at "handed to the provider". Statistics and the email.message.* webhooks are missing
email.bounced, email.complainedBad addresses and spam complaints are not suppressed
contact.updatedSomeone who unsubscribes from a Resend broadcast is not added to the unsubscribe list here

Resend must reach that URL. A local email-service needs a tunnel. Each delivery on the Resend webhook page shows the response: 200 is accepted, 401 means the signing secret does not match.

Leave tracking off​

In each domain's settings, leave open and click tracking off. Click tracking rewrites every link through Resend, sign-in links included.

Plan limits​

Each broadcast adds its recipients as Resend contacts, in one segment per language named {name} ({language}) #{id}. Contacts count toward the Resend marketing plan and are not deleted after the send.

A company with its own Resend account​

The company repeats the steps on its own account, then:

  • Saves its Full access key, From address, and Bulk From address in the admin under Email > Provider, with provider Resend
  • Points its Resend webhook at https://email.shellui.com/api/v1/provider-webhooks/resend/all?company_id=42. That URL accepts only the company's signing secret, and its events only update that company's messages and broadcasts
  • Stores the signing secret through the API. The admin form has no field for it yet

from_email is required on every PUT. The stored API key is kept when credentials is omitted. The request uses an identity JWT of a staff member or the company owner:

curl -X PUT "https://email.shellui.com/api/v1/provider?company_id=42" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"provider":"resend","from_email":"no-reply@acme.com","webhook_secret":"whsec_example"}'

Amazon SES​

Amazon SES is a company provider. It is not a platform fallback.

Company credentials:

{
"access_key_id": "AKIAEXAMPLE",
"secret_access_key": "secret",
"region": "eu-central-2",
"configuration_set": "shellui-events"
}
  • access_key_id and secret_access_key are required. Both are encrypted with the rest of the credentials and never returned. credentials_hint shows the last four characters of the secret
  • region defaults to eu-central-2 (Zurich). It must look like an AWS region, for example eu-west-1, or the save returns validation_failed with field_errors.region set to invalid_region
  • configuration_set is optional. Set it to send SES events to a configuration set

The adapter calls the SESv2 API (POST https://email.{region}.amazonaws.com/v2/email/outbound-emails) and signs each request with AWS Signature Version 4. It does not use SMTP, so it works in regions with no SES SMTP endpoint, such as Zurich.

What the adapter sends:

  • HTML and text bodies, the From name, and the recipient
  • Message headers, including List-Unsubscribe and List-Unsubscribe-Post on the bulk lane. A Reply-To header becomes ReplyToAddresses
  • Message tags as SES EmailTags, plus a message_id tag. Characters SES refuses in tags become _

How errors map:

SES answerResult
HTTP 429, TooManyRequestsException, LimitExceededExceptionRetryable, provider_rate_limited
HTTP 5xxRetryable, provider_unavailable
HTTP 401 or 403, AccountSuspendedException, SendingPausedExceptionprovider_unauthorized, the company lane is paused
MessageRejected, MailFromDomainNotVerifiedException, NotFoundException, other 4xxFails, provider_rejected

SES has no idempotency key. A retry after a timeout can send the message twice.

Broadcasts from a company on SES go through the bulk lane, one message per recipient.

Bounce and complaint events from SES are not read yet. Suppress bad addresses with the SES account-level suppression list.

Amazon SES account, before mail leaves​

  1. In SES > Identities in the region you use, verify the sending domain (Easy DKIM) or the From address
  2. Request production access. A sandbox account only sends to verified addresses
  3. Create an IAM user for email-service with only this policy, then create an access key for it:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ses:SendEmail",
"Resource": [
"arn:aws:ses:eu-central-2:123456789012:identity/acme.com",
"arn:aws:ses:eu-central-2:123456789012:configuration-set/shellui-events"
]
}
]
}

Drop the configuration set line if you do not use one. Then save the provider:

curl -X PUT "https://email.shellui.com/api/v1/provider?company_id=42" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"provider":"ses","from_email":"no-reply@acme.com","credentials":{"access_key_id":"AKIAEXAMPLE","secret_access_key":"secret","region":"eu-central-2"}}'

SMTP​

Company SMTP is off unless EMAIL_ALLOW_COMPANY_SMTP=true. Saving provider: "smtp" while it is off returns company_smtp_disabled. When it is on, host is resolved and rejected unless the address is public (provider_host_not_public). The worker connects to that public address. The platform relay in EMAIL_HOST is operator configuration and is not gated by this flag. A trusted_platform flag, or any key starting with _, in company credentials is ignored and is not stored. Only credentials that match the configured relay (host, port, username, and password) skip the public-host pin.

Company credentials:

{
"host": "smtp.example.com",
"port": 587,
"username": "mailer",
"password": "secret",
"use_tls": true,
"use_ssl": false
}

Message-ID is <{message_id}@email.shellui.com> so a retry stays the same message. Platform fallback uses EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS, and EMAIL_USE_SSL.

After the auth lane exhausts its short retries, the worker tries the platform SMTP credentials once (smtp_failover) if they are set and the company provider was not already SMTP.

Per company and platform fallback​

Each company stores one provider on PUT /api/v1/provider. Secrets are Fernet-encrypted with EMAIL_CREDENTIALS_KEY. Responses include configured and credentials_hint (a mask plus the last four characters). They never include the secret.

If the company has no configured provider, auth mail uses the platform fallback (Resend or SMTP from the environment, From DEFAULT_FROM_EMAIL). Non-auth mail does that only when the company id is listed in EMAIL_PLATFORM_COMPANY_IDS. Every other company receives platform_sender_not_allowed and must save its own provider. A company that is not on that list cannot set its From address to DEFAULT_FROM_EMAIL or BULK_FROM_EMAIL.

Add Mailjet​

Mailjet is the next provider. The module apps/providers/mailjet.py is present and not registered.

To enable it:

  1. Implement MailjetProvider.send in apps/providers/mailjet.py. POST https://api.mailjet.com/v3.1/send with HTTP basic auth (api_key and secret_key from the company credentials). Read the provider message id from Messages[0].To[0].MessageID. Return ProviderResult. Treat HTTP 429 and 5xx as retryable. Treat 401 and 403 as provider_unauthorized.
  2. Register the instance in apps.providers.registry.PROVIDERS.
  3. Add mailjet to ACTIVE_PROVIDER_NAMES in that same module.
  4. If Mailjet signs webhooks, add a parser next to apps/providers/webhooks and a route under /api/v1/provider-webhooks/mailjet/.

No worker, template, or rule changes. Callers only see the provider name.