How to add Postmark sender domains with the Bubble API Connector

Setting Up the API Connector in Bubble

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 their own domain. So what I'm after help with is kind of like, say setting up with the API, the API connector so that they can add their domains and it gets verified automatically without having to come through us manually.

Understanding Postmark's Email Sending Options

Okay, and just to check you're aware that Postmark offers two different approaches for sending emails on some of us 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, is that correct?

Configuring the API in Bubble

Absolutely, yeah, definitely the second option of just being able to send it via their domains rather than ours. Okay, so I think we'll start by, if you click on create domain, the sub option in the API documentation on the left hand column, yeah. And we will go into the Bubble API connector. And so I'll just take you through each of the different elements here.

Setting Up the API Call

So the API name that you can put in that top field, the Postmark. Okay, and then if you click expand on the sub group there, we will have to, each of these sub groups will need to be created for each individual call. So we might end up with two or three because 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 wanna 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.

Configuring the API Request

Okay, and then if we go back to documentation, we'll be flicking back to the pause between them 'cause 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 quotes, so this part here? Yeah, and you copy that and then in Bubble, we put that into that field there. But our double check, I think it said post, if we flick backwards between them. Yes, so it'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.

Adding Headers to the API Call

Okay, and then let's go back into Postmark 'cause we just have to look at how we authenticate the call. So we have the lines that start with H, that stands for header, and then D stands for data, but I think it 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, so if you copy that line.

Configuring Shared Headers

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 wouldn'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 that up and then get rid of the colon.

Adding More Shared Headers

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. So we can add another shared. 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, the whole section. Yeah, and then the account token, that's what we're going to retrieve it. And that's the sensitive data that we'll cycle at the end of the call.

Understanding Postmark API Tokens

Okay. 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 on this sending templates to emails, you would use the server level because the templates must go through one of the servers you've created in Postmark. But domains are on the account level. So we need the account level token, which we should be able to find within your account. Yeah, 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.

Configuring the API Call Body

Okay. And so that goes in there. Yep. 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. We just have to match up the fields that are required. So looking at now the sensor column of the API documentation, we look to see what sort of format it expects to receive the data in. So we need a name and path domain. So I think you have to create that yourself.

Adding Dynamic Data to the API Call

No, okay, fine. So name and return path domain. Let's go back to the Bubble answer. And so in... In fact, 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 me, please. And then if you highlight everything including the square brackets after the single quote, after D, up to the next single quote in the... So here, so all of that? Yeah, yes. You can copy that, but we then just need to get rid of the single quote marks.

Configuring Dynamic Fields in Bubble

Oh, I see. Sorry, if I just... Cool. And that's going... And that goes in the body. Down here? Yep. Okay. So the header there in Bubble gives us a clue of what to do next, which is to use square... Sorry, triangle brackets to allow... We now are 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.

Testing the API Call

Like that? Yeah, it needs to be a triangle bracket, usually on the comma and the full stop on the keyboard. Not a curly bracket. Oh, okay, sorry. Using the what? Sorry, the... Oh, I see what you're saying. Triangle, that's it. Okay, and 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 bit can stay the same. I mean, there is the option to customize it, but let's just leave it the same. So I would put in removejustexample.com and replace that with... Yeah, exactly the same thing. Open triangle brackets. I'm not sure how Bubble will behave here by putting two 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 backend 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 at a point to test it. Yeah, probably.

Testing the API Call with Sample Data

Okay, so we can test it without actually having to build the 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've got a domain, then we can test this on. Yes, yep. Yeah, I've got my last one. Oh, actually one that's not, yes, no, we have. We have, but one that's not already set up in there. That's fine. Yeah. 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 it's they're not verified. So if you just have a domain name we can use for testing that isn't already in the Postmark account. Yeah.

Formatting Domain Names for API Calls

Okay, so if we hop back onto the API documentation, just so I can point out a couple of things, you'll want to either clearly express to your users when you build this into a form on the in your Bubble app UI editor, there's a format the domain name is required in. So you don't want HTTPS, you don't want WW dot 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'll turn 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 dot whatever the root domain is, but yeah.

Initializing the API Call

Yeah. Cool, let's go back into the Bubble editor and let's test that, because if it goes through, then we've put everything in the right places. So you can go back and you can click initialize 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.

Handling API Response Data

Yeah, I've definitely seen that as well. So 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, so I don't know if it would do this, but if an ID began with zero, then if it's class 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 initialized and it's not returned an error, you can use that in a workflow.

Next Steps: Building the 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? Yeah, definitely because I can obviously, now I've got that kind of understanding, I can obviously go through the rest of these and kind of, you know, model together what we've just done. So I did do a quick form of just their name and the email they do, 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.

Creating the Workflow for Domain Verification

Okay, so yeah, let's build the 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 gonna 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 gonna be doing it once. So yeah, verify, okay, so then we can add an action in here. And so now if you go into plugins, sorry, in the, I wasn't clear there. 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, it should be there, yeah, 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 wanna clarify that?

Saving Domain Information to User Fields

To, hold on. Yeah, 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 returned 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. So you could do it, yeah, 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. SPF text value. Let's do one thing at a time. So we need domain ID, let's add that in. So if you move, get back into the editor and onto your workflow. Yeah, so that's how the field called domain ID and that's of text. Okay, and now we can say result of step one ID. So then we just have to work out the other key bits because so domain ID is 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.

Saving Additional Domain Verification Information

So I was just finding a little bit tricky to work out, but if we go back onto the documentation, please. And then if we scroll down to the response and I was have a quick skim of (mumbles) Yes, so we're definitely gonna need the SPF text value and the DKIM pending host. Just wondering what's the DKIM pending text value? (mumbles) 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 sorry, so it was, sorry, what was the first one? It was? SPF text value, yeah. And that's changed. 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 other one you said was what one, sorry? The DKIM pending host. And the text value? Yeah. (mumbles) Okay, and then if we go back, I think that's just possible, one or two