mailgun-js-boland API completeness and forward stability

API completeness and forward stability

Open buschtoens opened this issue 10 years ago • 16 comments

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`

[x] POST /<domain>/messages
[x] POST /<domain>/messages.mime
[x] GET domains/<domain>/messages
[x] DELETE domains/<domain>/messages/<message>

Retrieving and deleting stored messages would kick ass.

`/domains`

[x] GET /domains
[x] GET /domains/<domain>
[x] POST /domains
[x] DELETE /domains/<domain>
[x] GET /domains/<domain>/credentials
[x] POST /domains/<domain>/credentials
[x] PUT /domains/<domain>/credentials/<login>
[x] DELETE /domains/<domain>/credentials/<login>

`/<domain>/unsubscribes`

[x] GET /<domain>/unsubscribes
[x] GET /<domain>/unsubscribes/<address>
[x] DELETE /<domain>/unsubscribes/<address or id>
[x] POST /<domain>/unsubscribes

`/<domain>/complaints`

[x] GET /<domain>/complaints
[x] GET /<domain>/complaints/<address>
[x] POST /<domain>/complaints
[x] DELETE /<domain>/complaints/<address>

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

`/<domain>/bounces`

[x] GET /<domain>/bounces
[x] GET /<domain>/bounces/<address>
[x] POST /<domain>/bounces
[x] DELETE /<domain>/bounces/<address>

Stats

[x] GET /<domain>/stats
[x] DELETE /<domain>/tags

Events

[x] GET /<domain>/events

`/routes/`

[x] GET /routes
[x] GET /routes/<id>
[x] POST /routes
[x] PUT /routes/<id>
[x] DELETE /routes/<id>

`/<domain>/campaigns`

[x] GET /<domain>/campaigns
[x] GET /<domain>/campaigns/<id>
[x] POST /<domain>/campaigns
[x] PUT /<domain>/campaigns/<id>
[x] DELETE /<domain>/campaigns/<id>
[ ] GET /<domain>/campaigns/<id>/events
[ ] GET /<domain>/campaigns/<id>/stats
[ ] GET /<domain>/campaigns/<id>/clicks
[ ] GET /<domain>/campaigns/<id>/opens
[ ] GET /<domain>/campaigns/<id>/unsubscribes
[ ] GET /<domain>/campaigns/<id>/complaints

`/<domain>/webhooks`

[ ] GET /domains/<domain>/webhooks
[ ] GET /domains/<domain>/webhooks/<webhookname>
[ ] POST /domains/<domain>/webhooks
[ ] PUT /domains/<domain>/webhooks/<webhookname>
[ ] DELETE /domains/<domain>/webhooks/<webhookname>

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

`/lists/`

[x] GET /lists
[x] GET /lists/<address>
[x] POST /lists
[x] PUT /lists/<address>
[x] DELETE /lists/<address>
[x] GET /lists/<address>/members
[x] GET /lists/<address>/members/<member_address>
[x] POST /lists/<address>/members
[x] PUT /lists/<address>/members/<member_address>
[x] POST /lists/<address>/members.json I think this one's buggy.
[x] DELETE /lists/<address>/members/<member_address>

`/address/`

[x] GET /address/validate
[x] GET /address/parse

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

May 04 '14 03:05 buschtoens

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.

May 04 '14 15:05 bojand

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).

May 08 '14 17:05 buschtoens

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

May 08 '14 17:05 bojand

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.

May 08 '14 17:05 bojand

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

Jun 01 '14 22:06 jayzeng

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 :)

Jun 02 '14 12:06 bojand

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 :)

Jun 02 '14 16:06 jayzeng

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.

Jun 02 '14 16:06 bojand

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.

Jun 02 '14 16:06 jayzeng

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

Jun 03 '14 01:06 bojand

@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.

Jun 10 '14 00:06 bojand

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

Jun 03 '15 14:06 kenperkins

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.

Jun 03 '15 15:06 bojand

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!

Jun 03 '15 16:06 kenperkins

Hello,

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

Thanks

Jan 23 '17 16:01 kbariotis

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

Jan 24 '17 01:01 bojand

mailgun-js-boland mailgun-js-boland copied to clipboard

API completeness and forward stability

Stats

Events

mailgun-js-boland
mailgun-js-boland copied to clipboard