Webhooks are a way to receive HTTP POST requests from Hyvor Relay when certain events occur. They are useful to sync state (email sending status) between Hyvor Relay and your application or to trigger actions in your application based on events in Hyvor Relay.
send.recipient.accepted is triggered when an email is accepted by the recipient SMTP server.
This can be triggered once for a recipient of a send. It indicates that the email has been successfully
delivered to the recipient's server, but it does not guarantee that the email has been delivered
to the recipient's inbox. send.recipient.bounced or send.recipient.complained can be triggered
later if the email is not delivered to the recipient's inbox (ex: when the mailbox is full, or if
the email provider's spam detector detects the mail as spam) or if the recipient marks it as spam.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt;
}Objects: Send, SendRecipient, SendAttempt
send.recipient.deferred is triggered when an email is temporarily deferred by the recipient
SMTP server. This can happen for various reasons, such as the recipient's server being busy or
because of greylisting. Hyvor Relay will
retry sending the email a few more times before giving up. You can expect a send.recipient.accepted or send.recipient.bounced event later.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt;
}Objects: Send, SendRecipient, SendAttempt
send.recipient.bounced is triggered when an email is permanently rejected by the recipient SMTP
server. This can happen for various reasons, such as the recipient's email address not existing or
the recipient's server rejecting the email due to spam filters.
send.recipient.bounced event is
triggered immediately.send.recipient.accepted event is triggered first,
followed by the send.recipient.bounced event when the bounce is detected.If we detect a hard bounce (permanent failure) for a send, the email address is automatically added to your project's suppression list. This means that you cannot send emails to that email address again unless you manually remove it from the suppression list. This is to prevent sending emails to invalid email addresses, which can harm your sender reputation.
{
send: Send;
recipient: SendRecipient;
attempt: SendAttempt | null;
bounce: Bounce;
}Objects: Send, SendRecipient, SendAttempt Bounce
When a recipient marks an email as spam, the email provider sends a complaint, called a Feedback
Loop (FBL), to Hyvor Relay. Hyvor Relay is configured to receive FBLs from major email
providers.bind: We process these complaints and trigger the send.recipient.complained event. This
event indicates that the recipient has marked the email as spam or junk. When this event is triggered,
the email address is automatically added to your project's suppression list, similar to when a hard
bounce occurs.
{
send: Send;
recipient: SendRecipient;
complaint: Complaint;
}Objects: Send, SendRecipient, Complaint
This event is triggered when a new domain is created in your Hyvor Relay project.
{
domain: Domain;
}Objects: Domain
This event is triggered when the status of a domain changes.
{
domain: Domain;
old_status: 'pending' | 'active' | 'warning' | 'suspended';
new_status: 'pending' | 'active' | 'warning' | 'suspended';
dkim_result: {
verified: boolean;
checked_at: number;
error_message: string | null;
}
}Objects: Domain
This event is triggered when a domain is deleted from your Hyvor Relay project.
{
domain: Domain;
}Objects: Domain
This event is triggered when a suppression is created for an outgoing email. This could either
be due to a hard-bounce or a complaint.
{
suppression: Suppression;
}Objects: Suppression
This event is triggered when a suppression is deleted from your Hyvor Relay project.
{
suppression: Suppression;
}Objects: Suppression
When Hyvor Relay sends a webhook, it expects a 2xx HTTP response code from your
application. If it does not receive a 2xx response, it will retry sending the webhook
up to 6 times with the following intervals between retries:
If all retries fail, the webhook delivery will be marked as failed, and you can view the delivery status in the Hyvor Relay Console, including the error message received from your server.