Send an email

Sends one email from the site the key belongs to. The email is checked for spam, suppressed addresses and unsubscribes, sent, and written to the email log.

Headers#

Body#

Unknown fields are ignored.

Request#

curl -X POST https://securessmtp.com/api/v1/mail/send \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "[email protected]",
  "subject": "Your order #1042 has shipped",
  "html": "<p>Hi Sam,</p><p>Your order #1042 is on its way.</p>",
  "text": "Hi Sam,\n\nYour order #1042 is on its way.",
  "from": {
    "name": "Acme Store"
  },
  "reply_to": "[email protected]",
  "source_plugin": "orders-service"
}'

With a template

curl -X POST https://securessmtp.com/api/v1/mail/send \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "[email protected]",
  "template": "order-shipped",
  "data": {
    "first_name": "Sam",
    "order_number": 1042
  }
}'

With an attachment

curl -X POST https://securessmtp.com/api/v1/mail/send \
  -H "x-securessmtp-api-key: $SECURESSMTP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "[email protected]",
  "subject": "Invoice 1042",
  "text": "Your invoice is attached.",
  "attachments": [
    {
      "filename": "invoice-1042.pdf",
      "content": "JVBERi0xLjcKJ...",
      "content_type": "application/pdf"
    }
  ]
}'

Response#

{
  "ok": true,
  "sent": true,
  "mode": "relay",
  "message_id": "<[email protected]>"
}

Errors#

Errors have "ok": false, "sent": false and a reason. Checks run in the order below; the first one that fails answers.

send_failed includes these error values:

• all_recipients_suppressed — every to address is on the suppression list. See Bounces and suppressions.
• all_recipients_unsubscribed — every to address unsubscribed from this site. See Unsubscribe links.
• Any other text — the mail server did not accept the email.

All error values are listed in the Error catalogue.

Notes#

• Suppressions and unsubscribes. Suppressed addresses, and addresses that unsubscribed from this site, are removed from to before sending; the rest still get the email. cc and bcc are not checked.
• Held contact-form spam. When source_plugin is a known form plugin (for example contact-form-7, wpforms, gravityforms) or the subject looks like a contact-form notification, the message gets a contact-form spam check. Spam at 90% confidence or more is not sent and is logged as flagged, but the answer is { "ok": true, "sent": true, "held": true, "reason": "held_as_spam" } so the WordPress plugin does not send it another way. See Spam protection.
• Spam checks. Content that scores 30–59 is sent and marked with a warning in the log; 60 or more is refused. Apart from contact-form notifications, the classifier checks every email for sites with fewer than 100 emails in the log, and about 1 in 20 after that (chosen by subject).
• Limits. The monthly email count is per account (all sites together), counts relay-mode emails only, and resets on the first day of each month (UTC). Emails sent from a verified domain do not count.
• No idempotency key. If you retry after a timeout, the email may be sent twice.
• The first successful send marks the site as verified.