Skip to main content

Webhooks

We can send optional Webhooks (HTTPS POST requests) to an endpoint of your choice when certain events happen in the OhMySMTP API.

To set this up, open the Webhooks section of your Domain. Here you can add or remove endpoints and see recently sent webhooks.

Note that endpoint URLs must use TLS/SSL, and start with https://

Webhooks are sent as JSON POST requests, with a Content-Type of application/json

Events

All webhook event bodies have two properties:

  • event a string with the event name, e.g. email.delivered
  • payload a JSON object containing the event details (see below for details)

Email Events

EventDescription
email.queuedOccurs when an email is added to the queue for sending
email.deliveredOccurs when an email is accepted by the recipient's SMTP server
email.deferredOccurs when an email soft-bounces and is marked for redelivery
email.bouncedOccurs when an email hard bounces, delivery will not be attempted again
email.spamOccurs when our internal filter identifies an email as spam, delivery will not be attempted

Payload Properties

KeyTypeDetailsNullable*
statusStringEmail status, one of either queued, delivered, deferred, bounced or spamNo
idIntegerReference ID of emailNo
domain_idIntegerReference ID of sending DomainNo
created_atDateTimeTimestamp of when the email was first received by our APINo
updated_atDateTimeTimestamp of when the email was last updated, typically a status changeNo
fromStringFrom email addressNo
toStringTo email address, may be a comma separated list if multiple recipients providedYes
htmlbodyStringHTML body in emailYes
textbodyStringText body in emailYes
ccStringCarbon Coop email address, may be a comma separated list if multiple recipients providedYes
bccStringBlind Carbon Copy email address, may be a comma separated list if multiple recipients providedYes
subjectStringEmail subjectYes
replytoStringReply to addressYes
message_idStringMessage ID set by OhMySMTP, in the format <message-id>@<mailer.ohmysmtp.com>No
list_unsubscribeStringList-Unsubscribe headerYes

Properties that are marked as nullable are optional and will appear as null in the body if undefined

Example Body

{
"event": "email.queued",
"payload": {
"status": "queued",
"id": 1,
"domain_id": 1,
"created_at": 2021-11-16T14:50:15.445Z,
"updated_at": 2021-11-16T14:50:15.445Z,
"from": "string",
"to": "string",
"htmlbody": "string",
"textbody": "string",
"cc": "string",
"bcc": "string",
"subject": "string",
"replyto": "string",
"message_id": "string",
"list_unsubscribe": "string"
}
}