search

mailgun / mailgun-js-boland

A simple Node.js helper module for Mailgun API.
http://bojand.github.io/mailgun-js
MIT License
895 stars 122 forks source link

API completeness and forward stability #31

Open buschtoens opened 10 years ago

buschtoens commented 10 years ago

So this is a list of all API endpoints and methods mentioned in the API docs. I think that this might be helpful for reaching 100 % completeness. Feel free to edit this and check finished methods.

I also nagged @mailgun, about the API schema on twitter. Maybe we should file an issue.

/<domain>/messages

Retrieving and deleting stored messages would kick ass.

/domains

This could be very useful for automated evaluation or notification of support personnel.

/<domain>/bounces

Webhooks support would be sexy. Maybe I can come around to submitting a PR.

/lists/

Not really neccessary. We could do this on our own, if needed.

bojand commented 10 years ago

Thanks for this list. Can you please elaborate more on the buggy-ness of bulk members add? If there is a failing test please create an issue with any relevant code. Or do you mean the api method is somehow impractical (ie. add())? Any better suggestions? I will try and get to the missing functionality as I can. Adding to schema is pretty trivial. It's just a matter of writing the tests and testing it all out that's a bit time consuming. Of course PR's are always welcome too. There are also the generic REST methods to accommodate missing endpoints. Thanks again.

buschtoens commented 10 years ago

tbh, I haven't tried member bulk adding yet, but in the docs, Mailgun states that you'll have to use POST /lists/<address>/members.json for that. But in the schema.js you're using POST /lists/{address}/members (missing the .json).

bojand commented 10 years ago

Ooh that's a bug! I'll fix it soon. Thanks.

bojand commented 10 years ago

Oh actually I forgot... it's handled in build.js:

// HACKY special case for members bulk add
    if(action.href === '/lists/{address}/members' && actionName === 'add') {
      action.href = '/lists/{address}/members.json'
    }

I'll try and improve this.

jayzeng commented 10 years ago

@bojand Appreciate the great library. Seems like a number of endpoints are still missing, any plan to cover the rest?

bojand commented 10 years ago

Hello, yes as I can get to them. It's a bit time consuming to cover the tests for some of these. I have updated this list with some additions I implemented some time ago (mainly the stats stuff). Are there any specific endpoints that would be beneficial more so sooner? I think I'll try to finish messages and campaigns first when I can. PR's always welcome too :)

jayzeng commented 10 years ago

Great, thanks. /<domain>/messages and Events are top on my list. Will be great if you can get to them soon, and I will see if I can send in some PRS :)

bojand commented 10 years ago

Actually I forgot, but GET domains/<domain>/messages/<message> and DELETE domains/<domain>/messages/<message> are implemented. It's in the schema. I couldn't figure out a good way to unit test it, so I am not sure if it's 100% working. But you can give it a try and let me know how it goes.

For example to get message info:

mailgun.messages('WyJhOTM4NDk1ODA3Iiw').info(function(err, msgInfo) {
   console.log(msgInfo);
});

Similarly to delete:

mailgun.messages('WyJhOTM4NDk1ODA3Iiw').delete(function(err, body) {
   console.log(body);
});

Docs

I will try and get to the Events sometime.

jayzeng commented 10 years ago

Just tried it on my side, 

mailgun.messages('20140602040452.32167.70583').info(function (err, msgInfo) {
    console.log(err);
    console.log(msgInfo);
});
[Error: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>The requested URL was not found on the server.</p><p>If you entered the URL manually please check your spelling and try again.</p>
]

Looks like the constructed the url is incorrect.

bojand commented 10 years ago

Ok, thanks for the feedback. Will try to address it soon. For now you should be able to use the generic rest methods.

bojand commented 10 years ago

@jayzeng events endpoint has been added in the 0.4.11 release that's on NPM now. Also I believe I have addressed the messages().info() URL issue. Please let me know. I do not have an easy way to unit test this right now. Might need to rewrite the tests to properly handle it.

kenperkins commented 9 years ago

So what's the state of turning the documented methods listed above into implemented functionality?

bojand commented 9 years ago

Hello, which methods specifically? Everything that's "checked off" should be implemented already. As for the other ones, they shouldn't be hard to add. It's mostly just a matter of adding the definitions to the schema file, and the functions should be built automatically. The tests for new functions are the more time consuming part I guess. Unfortunately I am really swamped with real work and life stuff right now to complete the library at the moment. Hope to get to it sometime in the future. But any endpoints not implemented should be accessible using the generic rest methods.

kenperkins commented 9 years ago

Ah, thanks for the clarifications. I quickly grepped the source looking for routes support and didn't find the code; I didn't realize you were using a JSON schema to generate the methods programatically.

Thanks for the update!

kbariotis commented 7 years ago

Hello,

I've noticed that there is no option for setting the Mailgun Testing mode. Any chance is planned to be implemented soon?

Thanks

bojand commented 7 years ago

You can just add o:testmode param to the send() request params and set it to true and that should work.