Email API

Mailboxes

A mailbox is a real email address on one of your verified domains — an inbox you can log into over IMAP, plus an SMTP credential you can point any app at. Create one when an address needs to receive mail or be used as an SMTP login.

You do not need a mailbox to send email

Once a domain is verified you can already send from any address on it — noreply@, hello@, alerts@ — with no mailbox at all. Just pass it as from on POST /api/v1/email/send. Create a mailbox only when you need to receive replies at that address or log in to it.

Before you start

The domain must exist on your account and be verified. See Domains for adding and verifying one. Creating a mailbox on an unverified domain returns 409.

If the domain was added as send only, its inbound mail still goes to your existing provider, so a mailbox there is useful as an SMTP credential rather than an inbox. To actually receive mail with us, add the domain with mode: "full".

POST/api/v1/domains/:domainId/mailboxes

Create a mailbox on a verified domain.

REQUEST

curl -X POST \
  https://api.sendcomms.com/api/v1/domains/dom_abc123/mailboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "hello"
  }'

Body Parameters

Field	Type	Description
userrequired	string	The part before the @ (e.g. "hello" creates hello@yourdomain.com). Letters, numbers, dots, dashes and underscores.
password	string	Optional. Minimum 8 characters. Leave it out and we generate a strong one for you.

RESPONSE201 Created

{
  "success": true,
  "data": {
    "email": "hello@yourdomain.com",
    "password": "shown-once-store-it",
    "smtp": {
      "host": "mail.sendcomms.com",
      "port": 587,
      "security": "STARTTLS",
      "username": "hello@yourdomain.com"
    },
    "imap": {
      "host": "mail.sendcomms.com",
      "port": 993,
      "security": "SSL/TLS",
      "username": "hello@yourdomain.com"
    }
    // imap is null on a send-only domain
  },
  "message": "Mailbox created. Copy the password now - it cannot be retrieved later."
}

The password is shown once

Store it as soon as you receive it — we cannot show it again. If you lose it, POST the same user again to reset the password to a new value.

Response Fields

Field	Type	Description
email	string	The full mailbox address that was created.
password	string	Shown once, in this response only. It is not stored in a retrievable form.
smtp	object	Outgoing server: host, port (587), security (STARTTLS) and username.
imap	object \| null	Incoming server: host, port (993), security (SSL/TLS) and username. Null on send-only domains, which have no inbox here — their mail still goes to your existing provider.

GET/api/v1/domains/:domainId/mailboxes

List the mailboxes that exist on a domain. Passwords are never returned.

RESPONSE200 OK

{
  "success": true,
  "data": {
    "mailboxes": ["hello@yourdomain.com", "support@yourdomain.com"]
  }
}

Connecting a mail client or app

Use the credentials exactly as returned. Port 587 with STARTTLS — not 465.

Outgoing (SMTP)

host: mail.sendcomms.com

port: 587

security: STARTTLS

username: the full address

Incoming (IMAP) — full hosting only

host: mail.sendcomms.com

port: 993

security: SSL/TLS

username: the full address

Send-only domains return imap: null — there is no inbox here, your mail keeps arriving at your existing provider.

Errors

Status	Meaning	When
`400`	Invalid mailbox name	The local part contains characters that are not allowed, or the password is shorter than 8 characters.
`404`	Domain not found	The domain id does not exist, or belongs to another account.
`409`	Domain not verified	The domain has not passed DNS verification yet. Add the DKIM record and verify before creating mailboxes.

← Domains Webhooks →