Unipile allow you to be notified when a sent email bounces back with the reason using webhooks.

Setup

1. Configure a webhook

Configure a webhook to receive the wanted events email.new.bounce

2. Handle events

In your webhook handler, you should now receive events with the following payload as soon as a bounced email is received in the mailbox.

{
  "reason": "This is the mail system at host mailer.acme.email.\n\nI'm sorry to have to inform you that your message could not be delivered to one or more recipients. It's attached below.\n\nFor further assistance, please send mail to postmaster.\n\nIf you do so, please include this problem report. You can delete your own text from the attached returned message.\n\nThe mail system",
  "date": "2025-08-14T14:30:00Z",
  "type": "no_such_recipient",
  "code": 550,
  "email": {} // Original email
}

Error types

Here is all error types you can encounter:

code	type	RFC Explanation
421	`service_not_available / server_busy / ip_blocked_spam`	The server is temporarily unavailable and closing the connection.
432	`password_needed`	Temporary authentication failure requiring a password update or reset (obsolete in modern RFCs but common).
450	`action_not_taken_mailbox_unavailable / rate_limited`	Requested action not taken; mailbox busy, unavailable, or temporarily rate-limited.
451	`action_aborted_local_error / timeout / protocol_violation`	Temporary processing error; local problem or protocol issue.
452	`insufficient_system_storage / mailbox_over_quota`	Action not taken due to insufficient storage or full mailbox.
454	`authentication_issue / protocol_violation`	Temporary authentication or TLS-related failure.
455	`server_unable_to_accommodate_parameters`	Server cannot accept provided parameters (unsupported or invalid).
500	`syntax_error`	Command unrecognized due to a syntax error.
501	`syntax_error_parameters / invalid_helo_ehlo`	Syntax error in command parameters or invalid HELO/EHLO argument.
502	`command_not_implemented`	Command recognized but not implemented by the server.
503	`bad_commands_sequence / no_identity_changes_permitted`	Bad sequence of commands or forbidden authentication state transition.
504	`parameter_not_implemented / unknown_auth_type`	Command parameter not implemented; unsupported authentication type.
530	`authentication_required`	Authentication required before sending mail.
550	`action_not_taken / no_such_recipient / spam_content`	Requested action not taken—mailbox unavailable or rejected as spam.
551	`user_not_local`	User not local; server suggests an alternate recipient/path.
552	`exceeded_storage_allocation / mailbox_over_quota`	Action aborted—storage limit exceeded.
553	`mailbox_name_not_allowed / no_such_recipient`	Invalid mailbox name or nonexistent recipient.
554	`transaction_failed / spam_content`	Transaction failed permanently; often spam or policy rejection.
555	`parameters_not_recognized / syntax_error`	MAIL/RCPT parameter not recognized; syntax error.