Saturday August 10, 2019; 11:21 AM EDT
AWS is a gift. Somehow one of the big tech companies decided that the PC era was worth continuing, and instead of locking up all the useful stuff inside their corporate wall, they went into business providing those tools to any developer who wants to use them. #- They aren't the only ones, Digital Ocean is very good too, but AWS does more. Another difference is that Digital Ocean's docs are the best, and AWS's doc are in some ways the worst. #
- First, I have to say AWS docs appear to have all the information about their services. So I can't say their docs are the worst in all ways, they aren't. The problem is the way the docs are written and organized makes it too hard for a newcomer, or someone who only wants to use the most basic functions, slightly beyond Hello World, to find the information they need. First you have to understand everything about the toolkit, and it's presented in a disjointed fashion where the docs assume you already know everything, which makes it virtually impossible for you to get the data you want. Every time I master another AWS toolkit it seems I write one of these pieces to commemorate the experience and hope somehow to encourage Amazon to make it easier for me next time. 💥#
- Anyway, last year I finally got their email-sending functionality to work. The only problem was that every email I sent via their service arrived in Gmail with a huge warning that it could be from a hacker (I knew it wasn't, it came from me). It wasn't until a couple of days ago that I learned what was happening and what I had to do to prevent it. #
- First what was happening: I was sending an email from dave.winer@gmail.com through amazonses.com. Gmail said we got the mail, but noticed you didn't send it through gmail.com. Therefore the the big colorful warning. #
- What I had to do to prevent it: Send the email from another domain and convince Amazon that I was authorized to use that domain. #
- This is the place to note that nowhere in the Amazon docs do they say it this clearly. They try to tell you what to do on this page with lots of links that center around a protocol called SPF. It turns out that SPF simply requires you to create a TXT record on the domain with a string that says what mail servers are allowed to use it to send mail, and that would be enough to convince AWS that you're cool. It makes sense, it connects the domain with a mail server. The person who set up the TXT record obviously is a god of that domain. But when I set this up per their instructions AWS still called the sender address invalid. #
- Then it turns out that I have to use a command line tool to give me a special domain name, and an encrypted value. This contradicts the earlier docs. And I had no idea how to get the command line tool to do this (it seems this would have been a good place for their docs to tell you or link to a place that tells you, but they don't). #
- It was at this point that I put the project down for a bit, went on Twitter, checked email, went for a walk, did something to cleanse the mental palate, came back to the problem and found docs that provided yet another option for convincing AWS that I was authorized to use an email address. #
- There is an interactive way to do it through the control panel for SES. This method worked, and in a familiar way. You tell it what email address you want to use and it sends a message to that address with a link. When you click the link AWS authenticates the address. Everyone who uses the web in 2019 knows how to do this. Why didn't their docs say up front, hey there's a very very very easy way to do this. #
- So now I can send email through SES and the receiver won't get a warning because I'm playing by the 2019 rules for email sending and using AWS to send the email. I'm a happy camper except for the fact that all this michegas took two days to sort out. #
- Final note: When we were working on SOAP many years ago, we were dealing with a similar problem. Our colleagues at large tech companies were adding an alphabet soup of protocols on top of it, and just when you thought you understood what they were doing they added another few, and you were back where you started. I got fed up with this because I just wanted to deploy applications and didn't care about all this extra stuff, so Jake Savin and I wrote what we called A Busy Developer's Guide to SOAP. It defined a subset of SOAP that we had verified that works, and provided examples for developers of SOAP implementations to test with to be sure they worked with this subset. We published it, and then logged off the mail lists and got to work writing our blogging and RSS software. It worked. We got what we wanted and the big companies got to add all kinds of extra stuff. It seems to me that AWS is in a similar place. Developers like me who want to build apps, and systems people who want to cover all the bases. #
