Skip to content

Add option for using a proxy to AtData Safe To Send API for FreshAddress Component#380

Merged
fernanDOTdo merged 2 commits into
mainfrom
fresh-address-proxy
Feb 18, 2026
Merged

Add option for using a proxy to AtData Safe To Send API for FreshAddress Component#380
fernanDOTdo merged 2 commits into
mainfrom
fresh-address-proxy

Conversation

@MichaelT372

@MichaelT372 MichaelT372 commented Feb 18, 2026

Copy link
Copy Markdown
Contributor

A new option has been added to the FreshAddress Component proxyUrl. This accepts a URL hosting a proxy to the AtData SafeToSendAPI: https://docs.atdata.com/reference/safe-to-send that returns the same structure as that API endpoint does.

This addition attempts to gracefully integrate with the current component with as few changes as possible and re-using patterns already defined by the component. When a proxyUrl option is provided, we simply substitute the API call and response handling to 2 new functions.

Differences from current implementation

  • The SendToSafe API does not return error messages but instead returns status codes https://docs.atdata.com/reference/status-codes-safe-to-send. These codes are inserted into the "faMessage" field.
  • The SendToSafe API does not have configurable rejection for different statuses, so we have implemented to reject "invalid" and "trap" statuses. The "unknown" status could be added too but it is rare and in my testing it is a false positive.https://docs.atdata.com/reference/email-status
  • The API does not return defined error messages so we use the fixed error message "This email address is not valid." When the API returns an email suggestion, we also add "Did you mean {first suggestion}?"

Redundancies and Fallbacks
These are in place to handle:

  • The API not responding
  • The API returns an error
  • The API returns a response in an unexpected format
  • The API request times out (5 seconds)

In these cases the form is allowed to be submitted.

Testing
Related Productive task: https://app.productive.io/2650-4site-interactive-studios-inc/tasks/16274112

The page can be tested on WWF's pages using a branch I built from this branch that is configured to use their proxy:

https://protect.worldwildlife.org/page/94262/donate/1?assets=fresh-address-proxy

Testing Criteria

  • Email addresses are correctly marked as valid when valid and the form can submit
  • Email addresses are correctly marked as invalid and the form submission is blocked
  • Email suggestion is displayed in error message when the API provides one.
  • When the API does not respond, I can still submit the form.
  • When the API returns an error, I can still submit the form.
  • When the API returns a response in an unexpected format, I can still submit the form.
  • When the API request times out, I can still submit the form.
  • 4Site Email Addresses bypasses the validation
  • Status, Message and Date field values are properly recorded (if applicable to client)
  • After submitting an invalid email, then changing to a valid email, I can submit the form.
  • When not using a proxyUrl, everything works as it did before.

@fernanDOTdo
fernanDOTdo merged commit 12f56e6 into main Feb 18, 2026
2 checks passed
@fernanDOTdo
fernanDOTdo deleted the fresh-address-proxy branch February 18, 2026 15:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants