SMTP credentials

How sending works

• Sign in at mx1.shipmail.to on port 465 (TLS) or 587 (STARTTLS) with the credential's username and password.
• The envelope MAIL FROM and the From header must both be the sender's address. Recipients come from the SMTP envelope.
• Each message goes through the same checks, limits, suppression list, storage and counting as POST /v1/messages from that sender, and counts as transactional email.
• The sender's display name and Reply-To are always its own. A message with a different Reply-To is refused.
• A sender has at most 5 credentials. Creating the first one turns SMTP on for that sender.
• The API key acts for an Owner or Admin who can read the sender's mailbox; anyone else gets 403. A credential acts for the person who created it. Once they leave the organization or lose access to the sender's mailbox, its messages are refused, and a new credential is needed.

The SMTP credential object

{
  "object": "smtp_credential",
  "id": "smtpc_0123456789abcdefghjkmnpq",
  "from": "notifications@notify.example.com",
  "name": "Supabase Auth",
  "username": "smtp-smtpc_0123456789abcdefghjkmnpq@txsmtp.shipmail.to",
  "host": "mx1.shipmail.to",
  "ports": [
    { "port": 465, "security": "tls" },
    { "port": 587, "security": "starttls" }
  ],
  "last_used_at": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}

List SMTP credentials

Returns { "object": "list", "data": [...] } with the active credentials, newest first, without pagination. Pass from=notifications@notify.example.com to list one sender's credentials. A key limited to some mailboxes sees only the credentials of senders on those mailboxes. Passwords are never returned.

Create an SMTP credential

{
  "from": "notifications@notify.example.com",
  "name": "Supabase Auth"
}

Returns 201 with the credential and a password field. Save the password now: Shipmail keeps no copy and never shows it again. For the same reason the request refuses an Idempotency-Key header.

Revoke an SMTP credential

Returns 204. Clients that use the credential can no longer sign in or send. Returns 404 when the credential does not exist, is already revoked, or belongs to a mailbox the key cannot reach.

Errors