Connect a sending provider

You bring your own provider account. Hermeticor sends through it, so your reputation, pricing and data stay yours.

What you need first

• An account with an email provider (Amazon SES, SendGrid, Postmark, Resend, Mailgun or any SMTP server), or Twilio for SMS.

• Its API key or SMTP login.

• A secret key with connections:write (see Quickstart).

1. See what you can connect

curl -s "$BASE/v1/providers" -H "Authorization: Bearer $HERMETICA_API_KEY"

Each item lists credentialFields: the keys to send, whether each goes in credentials (encrypted, never shown again, secret: true) or config, and which are required. A missing required field answers 400 naming it, before Hermeticor calls the provider.

No provider account yet? If your Hermeticor server runs the demo mail sink, connect {"kind":"smtp","family":"smtp","credentials":{"host":"hermetica-mailpit","port":1025}}. It needs no username and catches every message instead of delivering it, so you can try campaigns and journeys safely.

2. Create the connection

Hermeticor checks the credentials with the provider before it saves them. This SMTP example also works for most hosted mail services:

curl -s -X POST "$BASE/v1/connections" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: conn-smtp-1" \
  -d '{"kind":"smtp","family":"smtp","name":"Main SMTP",
       "credentials":{"host":"smtp.example.com","port":587,"secure":false,"user":"hello@example.com","pass":"..."},
       "purposesAllowed":["marketing","transactional"]}'

The answer is 201 with health: healthy. A missing required field gives 400 with details.missing; credentials the provider refuses give 412 Connection verification failed with the provider's own status. Your secret is never echoed back.

Common credential fields (GET /v1/providers has the full list, with optional config fields):

Gmail and Microsoft 365 mailboxes connect by signing in: POST /v1/connections/oauth/google/start (or microsoft). If your Hermeticor server has no OAuth app set up, this answers 412.

3. Test it and set limits

curl -s -X POST "$BASE/v1/connections/<connectionId>/test" -H "Authorization: Bearer $HERMETICA_API_KEY"
# {"ok":true,"state":"healthy"}

curl -s -X PATCH "$BASE/v1/connections/<connectionId>" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"dailyCap":500,"hourlyCap":100,"timezone":"America/New_York"}'

To rotate credentials, PATCH with {"credentials":{...}}. The new set is checked first; a bad set leaves the old one working. Pause and resume with POST /v1/connections/<id>/pause and /resume.

4. Add a sender

curl -s -X POST "$BASE/v1/connections/<connectionId>/senders" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel":"email","fromEmail":"hello@example.com","fromName":"Acme","replyTo":"hello@example.com"}'

• SMTP and mailbox senders: verify by sign-in with POST /v1/connections/<connectionId>/senders/<senderId>/verify.

• API providers (SES, SendGrid and so on): verify the sending domain instead.

Next: Verify a sending domain.