Hi. So I am after some help with setting up the API with Postmark in order to have my users send emails directly through the app using in their own domain. So what I'm asked to help with is setting up with the API and the API connector so that they can add their domains and it gets verified automatically without having to come through us manually.
Okay. Just to check, you're aware that Postmark offers two different approaches for sending emails on someone else's behalf. There is the sender signatures, which allows you to send from one particular email address and it's slightly quicker, but it sounds like you require like domain level to be able to send from any email address on that domain.
Yeah, there's definitely the second option of just being able to send it via their domains rather than ours.
Examining Postmark API documentations
Okay. So I think we'll start by if you click on Create Domain, the sub option in the Postmark API documentation on the left hand column, and we will go into the Bubble API connector. And so I'll just take you through each of the different elements here. So the API name that you can put in that top field there, Postmark. Okay. And then if you click expand on the subgroup there, each of these subgroups will need to be created for each individual call. So we might end up with two or three because of the additional verification steps. So in name you can put 'Create domain' and then use as in Bubble, there are two different ways that you can use an API connection. Data would be useful if you're like calling a weather website to get the latest weather. But we actually want to set this to Action because we want it to be a step in a workflow. So if you change data to action for me, please.
Okay. And then if we go back to documentation, we'll be flipping back to the force between them because we just have to match up the different fields. So where it says cURL, if you can copy everything within the quotes but not including the quotes.
So not including the quote so this part here.
Bubble API Connector
Yup, you copy that. And then in Bubble, we put that into that field there. But I'll double check I think it said POST if we flip backwards between them. Yes, that's post. And so POST is the common call for if you are imparting data to another service, whereas if you're receiving it, it's often get but it's a bit of a blurred line there. Okay. And then let's go back into Postmark because we just have to look at how we authenticate the call.
We have the lines that start with H that stands for header and then D stands for data. But I think it's helpful to think of that as the body of the call. So we have to copy each of those lines. But the colon is a point where it gets split in the Bubble app. So if you either copy the whole thing and we'll break it up in the Bubble app. Yeah, copy that line.
Okay.
And then with Bubble, we get the opportunity to... You can either put shared headers or you can put headers specific to the call. I think we should put these in shared because they're likely to be required in every single call that we make, at least for domain verification. So if you don't mind scrolling up, we'll put them in shared header. Okay, so then if you paste it into there, please,
In the key, yeah, yeah.
Okay, so the key is just the accept and then the value is the application JSON. So if you just break up and then get rid of the colon.
Okay. And no spaces as well.
Yeah, no spaces. Yeah. This whole process is really a game of everything has to be in the right place, otherwise it doesn't work. We can add another shared header and there's two more to do, I think.
Okay, so we've got content-type.
With the X. Yeah, that whole section.
Postmark account token
Yeah. And then the account token. That's what we're going to retrieve it. And that's the sensitive data that will cycle at the end of the call. But we need it in there in order to test it now.
So this can cause a bit of confusion. I've seen before. Postmark has two different types of API key or API token. There's a server level one and then there's an account level one. So if you were sending we got some videos and they're sending templates emails, you would use the server level because the template emails go through one of the servers you've created in Postmark. But the domains are on the account level. So we need the account level token, which we should be able to find within your account API tokens.
Yes.
So there's your account level token there on the left hand side so we can copy that. And then afterwards we will generate a new token and you'll have to update it.
Okay.
And so that goes in there. Okay. Now we do a similar thing, but we build up the content of the actual call itself. So yeah, you can hop back to the documentation and we just have to match up the fields that are required.
So looking at now the sender column of the API documentation, we look to see what sort of format it expects to receive the data in. So we need name and path domain. I think you have to create that yourself.
Okay, fine.
So name and return aftermath. Let's go back to the Bubble Editor. Let's make this easier on ourselves. We can just copy and paste the whole portion here and then update it. Sorry, go back to the documentation for you, please. And then if you highlight everything, including the square brackets after the single quote, after D up to the next single quote.
So all of that.
Yes, you can copy that. But we don't just need to get rid of the single quote marks.
Oh, I see. Cool.
And that's going and that goes in the body down here.
Adding variables to Bubble API Connector
Okay, so the header there in Bubble gives us a clue of what to do next, which is to use square triangle brackets to allow we now identifying the merge tags, identifying the areas that we want to insert specific data into during our workflow. So you could highlight example.com and then you could type in there, open triangle bracket, domain name, close triangle bracket. Yeah, it needs to be a triangle bracket usually on the comma and the full stop on the keyboard not a curly bracket.
So that tells Bubble, this is where we want to add data in and be flexible with it. And then I think you could do the same in the return path domain, the subdomain that can stay the same. I mean, there is the option to customise it, but let's just leave it the same. So I would put in, remove just example.com and replace that with exactly the same thing, open triangle brackets. I'm not sure how Bubble will behave here by putting two of the same. I think it will probably be okay. Yeah, that's right. We can always come back to that if it doesn't work. And then if we unclick Private. Uncheck Private. So a row there, that's Private. That allows you to add your own data in the back end of Bubble in the API connector. But if we want to be able to add data in a workflow, we need to have it as unchecked on Private. Okay, now wondering if we're point to test it. Yeah, probably. Okay, so we can test it without actually having to build a workflow because we can put in a value in the value field that will be inserted into the places we've highlighted for dynamic data.
So it's not just occurred to me if we got a domain, then we can test this on yes.
Actually, yes. No, we have, we have. But one that's not already set up in there. That's fine.
I think at the very least we could use a domain name because we'll then work on the verification steps, but each of those steps will return whether it's verified or not. So we can get them working and they can just say they're not verified. If you just have a domain, then we can use for testing that isn't already in the Postmark account. Okay, so if we hop back onto the API documentation just so I can point out a couple of things you want to either clearly express to your users when you build this into a form in your Bubble app, UI editor, the format the domain name is required in. So you don't want https, you don't want www because that's technically a subdomain. What you want them to provide is the root domain. So either you go down the route of making it really clear what you want, or you'd have to work in kind of a few checks using 'does the field contain HTTPS' show them a warning, that sort of thing, because it has to be the root domain. Okay, no, sorry I said that back. It doesn't have to be the root domain, but I think your users would be expecting the root domain.
You could send it on like notifications.rootdomain.com. But yeah, cool. Let's go back into Bubble editor and let's test that because if it goes through, then we put everything in the right places so you can go back and you can click Initialise Call. Okay, brilliant.
So the API documentation has told us to expect all this data back. And this is good because otherwise it would just show us like a single line with an error message.
I've seen that before.
Our communication with the Postmark API has worked successfully. All of this can be left. We will need to refer back to the ID because from now on, when we perform the checks with Postmark, Postmark doesn't want the root domain, it wants the ID, which is that top figure there. So we can always come back to this. But I would just change the ID to text because I don't know if it would do this. But if an ID began with zero, then if it's classed as a number, it would get rid of the zero at the beginning. Whereas we want to treat it as a string of text. And then you can click save. And so now that that's been initialised and it's not returned an error, you can use that in a workflow.
I'm just wondering now what would be most helpful to you? Would it be helpful to quickly mock up a form on a page and then to build the workflow in?
Yes, definitely. Because now I've got that kind of understanding, I can obviously go through the rest these and kind of muddle together what we've just done. So I did do a quick form of just their name and the email. So I suppose that would be the domain. So, yeah, I think that would definitely be more helpful if we could just see it in the workflow.
Postmark domain ID
Okay, so, yeah, let's build a workflow on that verify button because you need to have a way of storing at least that domain ID. And then I think it also returns you're going to present your user with these are the changes they need to make to their DNS records. So actually, there's a few things we need to save now. Will users need to be able to verify multiple domains or is it just one per user?
One per user.
Okay, so that we don't need to create a data type for domains. We can save them to fields within User. Then we're only going to be doing it once. So, yeah, verify. Okay, so then we can add an Action in here. Now, if you go into Plugins sorry, I wasn't clear there. Sorry. If you go back onto Workflows and then add an action, then plugins and then scroll down to Postmark, because we set it as an action, there will now be a 'Create domain'. So our action that we've tested is now available there. And you can see that our public field is also available. So we update that with the input that we want the domain name placed into. I think you might want to clarify that. Do you see why you might want to clarify that, too? Okay, so then Bubble will make that call as step one. And then we can create additional steps in the workflow which do things with the data, return from step one, just like we saw in the pop up panel when we first submitted it. So we can add in a step two. And I would call this make changes to user.
Storing DNS record changes
So you could make changes to current user. And then if we go back into the API documentation, let's just get an idea of the types of responses. So we definitely need the SPF text value. Let's do one thing at a time. So we need domain ID. Let's add that in. So we will go back into the editor and onto your workflow. Let's add a field called domain ID and that's of text. And now we can say result of step one ID. So then we just have to work out the other key bits because domain ID for your internal use to refer to that domain name of future API calls. But we need to find the bits, the DNS changes that we want to display to the user. So I was just finding a little bit tricky to work out.
If we go back onto the documentation please. And then if we scroll down to the response and I'll just have a quick skim of... Yes. So we're definitely going to need the SPF text value and the DKIM pending hosting text value.
Okay. Let's just save everything just in case we need it. So I think we need to create fields for SPF text value, DKIM pending host, and DKIM pending text value.
Okay, so what was the first one?
It was SPF text value.
Yeah.
These fields that you're creating, they don't have to be identical, but it can help when you're referring back to them to label them the same.
Right, okay. And the one you said was what one? Sorry.
The DKIM pending host.
And the text value.
Yeah.
Okay. And then if we go back, I think that's just spotted one or two more. I'm trying to remember when you add a domain through the Postmark web interface, in fact, I'd recommend you copy how they've laid out because they will have done the research of how to express this to users. Not everyone's familiar with updating DNS records on their domains. So I think you could also do return path domain and return path domain CNAME value. I think then we've covered all of the elements that are required to be added to the domain name.
On this one here.
Yeah. Okay.
So are you happy now that we've got those key elements saved into the database and you can recall the necessary ones and display them to your users?
Yeah
I'm just a little bit aware of the time, but that's fine. I think this is going to make a really good video really helpful to many people. But I think just to kind of point you in the right direction of what's next
You will need to make those additional API calls using the domain ID, and they should return a status of whether it's pending or confirmed. And then you can update a field in your user. In order to hide that bit, you need to do this. Like I said, I would go and look at how the web interface for Postmark, how they guide people through making these changes to their domain, and I would build something similar.
Verify DKIM
What else is I going to say? Can we go back to the documentation, please? Yeah, I think and just to be scrolled up a little bit just to check the okay. And then let's have a look at the Verify DKIM call. Just so that you can tell me whether you're comfortable with okay.
If I just highlight the difference here, you can set up another call, and it's a PUT command this time and you be inserting dynamic data into the URL, into that domain ID field without the curly bracket. So that's where you put in that number that's returned that Postmark, now used to identify the domain name.
Right. Okay. So when I copied that over, that's when I do the triangle brackets.
Okay.
In fact, let's set that up. That will take us two minutes. Okay. And then I will just have to leave you. And I think you've got enough to work out otherwise you can book another call. Yes. So let's scroll down and create another call.
I've done another API. Hold on, let me get rid of that one.
So that would normally be used if you were adding an additional service or if there were two completely different ways of integrating in with the same service. But for now, we can add in another call.
Okay.
And then if you scroll down yeah. So we can call this verify DKIM, and then we can have it if you want them to click a button, then we set that as an action, and then it's a put command and we go into the API documentation and we can copy all of the cURL statements.
Okay and for some reason, probably for formatting, Bubble wants you to use square brackets here to insert the dynamic data. So if we replace the curly brackets with square brackets and then uncheck from private.
Okay.
And when you build this into your app, you'll be referring to that value in current user, but we've not saved that. So for the purpose of testing, if you click on manual, enter API response in the command above.
Yeah. It lets you get back to the data. So we can copy the ID from there just so we can test it.
Okay. And then we can try initialise call. And so what we're looking for is for the call to be successful and for it to return pending or... Yes. DKIM verification is false.
Summary
So once the users updated their DNS, and sometimes that can take up to 72 hours. Again, copying the Postmark page is going to explain this really well. Otherwise, they might just end up spamming the button to check it, but yeah, that provides you with the information. So you'd be looking for the DKIM verification to return true. And then you can give them a green light on that field and remove it. Is that okay? Okay.
Yeah. Amazing. Absolutely fantastic. Yeah. Thank you. That definitely gives me something to work with. It makes the API is 100% less daunting. Now, before I think, like I say, I just kind of looked at all of this, and I didn't have a clue what I was looking for.